collection.h

Go to the documentation of this file.

/*
    This file is part of darktable,
    Copyright (C) 2010-2012 Henrik Andersson.
    Copyright (C) 2010-2011, 2013 johannes hanika.
    Copyright (C) 2012 José Carlos García Sogo.
    Copyright (C) 2012, 2018, 2020 Pascal Obry.
    Copyright (C) 2012 Richard Wonka.
    Copyright (C) 2012 Simon Spannagel.
    Copyright (C) 2013 Gaspard Jankowiak.
    Copyright (C) 2013-2016, 2019 Tobias Ellinghaus.
    Copyright (C) 2013 Ulrich Pegelow.
    Copyright (C) 2014, 2016 Roman Lebedev.
    Copyright (C) 2015-2016 Jérémy Rosen.
    Copyright (C) 2015 Pedro Côrte-Real.
    Copyright (C) 2016, 2020-2022 Aldric Renaudin.
    Copyright (C) 2016 itinerarium.
    Copyright (C) 2017 luzpaz.
    Copyright (C) 2018 Mario Lueder.
    Copyright (C) 2018 Rick Yorgason.
    Copyright (C) 2018 Rikard Öxler.
    Copyright (C) 2018 Sam Smith.
    Copyright (C) 2018 Simon Legner.
    Copyright (C) 2019 rrd1.
    Copyright (C) 2020 Hanno Schwalm.
    Copyright (C) 2020 JP Verrue.
    Copyright (C) 2020-2021 Philippe Weyland.
    Copyright (C) 2021 Arnaud TANGUY.
    Copyright (C) 2021 Ralf Brown.
    Copyright (C) 2022-2023, 2025 Aurélien PIERRE.
    Copyright (C) 2022 Martin Bařinka.
    
    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_COMMON_COLLECTION_H
#define DT_COMMON_COLLECTION_H
 
#include <glib.h>
#include <glib/gi18n.h>
#include <inttypes.h>
#include "metadata/metadata.h"
 
#define NUM_LAST_COLLECTIONS 10
 
/* Recording the N most recently used collections is a GUI feature: the list exists to fill a
 * menu, and nothing in the collection backend reads it back. It lived here only because this
 * is where a collection change is noticed.
 *
 * It must run BEFORE DT_SIGNAL_COLLECTION_CHANGED is raised -- some listeners read the recents
 * list -- so it cannot simply become another listener. The backend therefore calls the handler
 * at exactly the point the old code did. */
typedef void (*dt_collection_recents_handler_t)(void);
 
void dt_collection_set_recents_handler(dt_collection_recents_handler_t handler);
 
typedef enum dt_collection_query_flags_t
{
  COLLECTION_QUERY_SIMPLE             = 0,      // a query with only select and where statement
  COLLECTION_QUERY_USE_SORT           = 1 << 0, // if query should include order by statement
  COLLECTION_QUERY_USE_LIMIT          = 1 << 1, // if query should include "limit ?1,?2" part
  COLLECTION_QUERY_USE_WHERE_EXT      = 1 << 2, // if query should include extended where part
  COLLECTION_QUERY_USE_ONLY_WHERE_EXT = 1 << 3  // if query should only use extended where part
} dt_collection_query_flags_t;
#define COLLECTION_QUERY_FULL (COLLECTION_QUERY_USE_SORT | COLLECTION_QUERY_USE_LIMIT)
 
typedef enum dt_collection_filter_flag_t
{
  COLLECTION_FILTER_NONE            = 0,
  COLLECTION_FILTER_ALTERED         = 1 << 0, // altered images
  COLLECTION_FILTER_UNALTERED       = 1 << 1, // unaltered images
  COLLECTION_FILTER_REJECTED        = 1 << 2, // rejected images
  COLLECTION_FILTER_0_STAR          = 1 << 3,
  COLLECTION_FILTER_1_STAR          = 1 << 4,
  COLLECTION_FILTER_2_STAR          = 1 << 5,
  COLLECTION_FILTER_3_STAR          = 1 << 6,
  COLLECTION_FILTER_4_STAR          = 1 << 7,
  COLLECTION_FILTER_5_STAR          = 1 << 8,
  COLLECTION_FILTER_RED             = 1 << 9,
  COLLECTION_FILTER_YELLOW          = 1 << 10,
  COLLECTION_FILTER_GREEN           = 1 << 11,
  COLLECTION_FILTER_BLUE            = 1 << 12,
  COLLECTION_FILTER_MAGENTA         = 1 << 13,
  COLLECTION_FILTER_WHITE           = 1 << 14, // white means "no color label"
  COLLECTION_FILTER_ALL             = (1 << 15) - 1, // all 15 defined flags
} dt_collection_filter_flag_t;
 
typedef enum dt_collection_sort_t
{
  DT_COLLECTION_SORT_NONE     = -1,
  DT_COLLECTION_SORT_FILENAME = 0,
  DT_COLLECTION_SORT_DATETIME,
  DT_COLLECTION_SORT_IMPORT_TIMESTAMP,
  DT_COLLECTION_SORT_CHANGE_TIMESTAMP,
  DT_COLLECTION_SORT_EXPORT_TIMESTAMP,
  DT_COLLECTION_SORT_PRINT_TIMESTAMP,
  DT_COLLECTION_SORT_RATING,
  DT_COLLECTION_SORT_ID,
  DT_COLLECTION_SORT_COLOR,
  DT_COLLECTION_SORT_GROUP,
  DT_COLLECTION_SORT_PATH,
  DT_COLLECTION_SORT_TITLE
} dt_collection_sort_t;
 
#define DT_COLLECTION_ORDER_FLAG 0x8000
 
/* NOTE: any reordeing in this module require a legacy_preset entry in src/libs/collect.c */
typedef enum dt_collection_properties_t
{
  DT_COLLECTION_PROP_FILMROLL = 0,
  DT_COLLECTION_PROP_FOLDERS,
  DT_COLLECTION_PROP_FILENAME,
 
  DT_COLLECTION_PROP_CAMERA,
  DT_COLLECTION_PROP_LENS,
  DT_COLLECTION_PROP_APERTURE,
  DT_COLLECTION_PROP_EXPOSURE,
  DT_COLLECTION_PROP_FOCAL_LENGTH,
  DT_COLLECTION_PROP_ISO,
 
  DT_COLLECTION_PROP_DAY,
  DT_COLLECTION_PROP_TIME,
  DT_COLLECTION_PROP_IMPORT_TIMESTAMP,
  DT_COLLECTION_PROP_CHANGE_TIMESTAMP,
  DT_COLLECTION_PROP_EXPORT_TIMESTAMP,
  DT_COLLECTION_PROP_PRINT_TIMESTAMP,
 
  DT_COLLECTION_PROP_GEOTAGGING,
  DT_COLLECTION_PROP_TAG,
  DT_COLLECTION_PROP_COLORLABEL,
  DT_COLLECTION_PROP_METADATA,
  DT_COLLECTION_PROP_GROUPING = DT_COLLECTION_PROP_METADATA + DT_METADATA_NUMBER,
  DT_COLLECTION_PROP_LOCAL_COPY,
 
  DT_COLLECTION_PROP_HISTORY,
  DT_COLLECTION_PROP_MODULE,
  DT_COLLECTION_PROP_ORDER,
  DT_COLLECTION_PROP_RATING,
 
  DT_COLLECTION_PROP_QUERY, // raw user-provided SQL WHERE expression (advanced)
 
  DT_COLLECTION_PROP_LAST,
 
  DT_COLLECTION_PROP_UNDEF,
  DT_COLLECTION_PROP_SORT
} dt_collection_properties_t;
 
typedef enum dt_collection_change_t
{
  DT_COLLECTION_CHANGE_NONE            = 0,
  DT_COLLECTION_CHANGE_NEW_QUERY       = 1, // a completly different query
  DT_COLLECTION_CHANGE_FILTER          = 2, // base query has been finetuned (filter, ...)
  DT_COLLECTION_CHANGE_RELOAD          = 3, // we have just reload the collection after images changes (query is identical)
  // Something changed elsewhere (e.g. an import landing outside the browsed folder) that
  // listeners with their own independent state may care about, but that is NOT a navigational
  // event: nothing about what the user is currently looking at changed. Listeners driven by user
  // navigation (scroll/focus/zoom resets) should treat this the same as NONE and do nothing;
  // listeners that keep their own counts (e.g. the Collect module's tag/camera/lens lists) should
  // still refresh. Deliberately its own value rather than reusing NONE: NONE already means "no
  // value" in non-signal contexts (see gui/actions/file.c's one-time init call), and overloading
  // it with this second, signal-specific meaning would make every future listener re-derive which
  // sense of NONE it is looking at.
  DT_COLLECTION_CHANGE_BACKGROUND_SYNC = 4
} dt_collection_change_t;
 
typedef struct dt_collection_rule_t
{
  dt_collection_properties_t property;
  int mode;              
  const char *text;      
  gboolean recursive;    
} dt_collection_rule_t;
 
typedef struct dt_collection_params_t
{
  dt_collection_query_flags_t query_flags;
 
  dt_collection_filter_flag_t filter_flags;
 
  char *text_filter;
 
  dt_collection_sort_t sort; // Has to be changed to a dt_collection_sort struct
  gint descending;
 
} dt_collection_params_t;
 
typedef struct dt_collection_t
{
  dt_collection_rule_t *rules;   
  int n_rules;
  unsigned int count;
  unsigned int tagid;
  dt_collection_params_t params;
  dt_collection_params_t store;
} dt_collection_t;
 
/* returns the name for the given collection property */
const char *dt_collection_name(dt_collection_properties_t prop);
 
// Interim accessor (Strategy B, doc/globals-migration.md): implemented by the module itself; long-term the handle should be carried on the job/view context (Strategy C).
// NULL in a GUI-less process (ansel-cli): the collection is lighttable query state, created by
// dt_gui_gtk_init() through dt_collection_init_global(). Every public function here accepts a
// NULL collection and degrades to a no-op / neutral result, so shared code paths need no guard.
dt_collection_t *dt_collection_get_global(void);
void dt_collection_init_global(void);
void dt_collection_cleanup_global(void);
 
dt_collection_t *dt_collection_new();
void dt_collection_free(const dt_collection_t *collection);
const dt_collection_params_t *dt_collection_params(const dt_collection_t *collection);
void dt_collection_get_makermodels(const gchar *filter, GList **sanitized, GList **exif);
gchar *dt_collection_get_makermodel(const char *exif_maker, const char *exif_model);
int dt_collection_update(const dt_collection_t *collection);
void dt_collection_reset(const dt_collection_t *collection);
void dt_collection_set_rules(const dt_collection_t *collection, const dt_collection_rule_t *rules,
                             const int n_rules);
 
dt_collection_filter_flag_t dt_collection_get_filter_flags(const dt_collection_t *collection);
void dt_collection_set_filter_flags(const dt_collection_t *collection, dt_collection_filter_flag_t flags);
 
dt_collection_query_flags_t dt_collection_get_query_flags(const dt_collection_t *collection);
void dt_collection_set_query_flags(const dt_collection_t *collection, dt_collection_query_flags_t flags);
 
char *dt_collection_get_text_filter(const dt_collection_t *collection);
void dt_collection_set_text_filter(const dt_collection_t *collection, char *text_filter);
 
void dt_collection_set_tag_id(dt_collection_t *collection, const uint32_t tagid);
 
typedef enum dt_collection_import_view_t
{
  DT_COLLECTION_IMPORT_VIEW_KEEP = 0,
  DT_COLLECTION_IMPORT_VIEW_GRID,
  DT_COLLECTION_IMPORT_VIEW_IMAGE
} dt_collection_import_view_t;
 
void dt_collection_load_filmroll(dt_collection_t *collection, const int32_t imgid,
                                 dt_collection_import_view_t view_policy, gboolean set_mouse_over);
 
gboolean dt_collection_get_browsed_folder(gchar *folder, size_t len, gboolean *recursive);
 
void dt_collection_notify_imported(const int32_t imgid, const gchar *known_image_folder, gint64 *last_refresh_us);
 
void dt_collection_set_sort(const dt_collection_t *collection, dt_collection_sort_t sort, gint reverse);
dt_collection_sort_t dt_collection_get_sort_field(const dt_collection_t *collection);
gboolean dt_collection_get_sort_descending(const dt_collection_t *collection);
gchar *dt_collection_get_sort_query(const dt_collection_t *collection);
 
uint32_t dt_collection_get_count(const dt_collection_t *collection);
int dt_collection_get_nth(const dt_collection_t *collection, int nth);
GList *dt_collection_get_all(const dt_collection_t *collection, int limit);
 
GList *dt_collection_get_images_for_rule(const dt_collection_properties_t property, const char *text,
                                         gboolean recursive);
 
typedef struct dt_collection_name_value_t
{
  char *name;  // raw/display value: folder path, tag name, formatted number/date, ...
  int id;      // film_roll id / tag id / running index, or 0
  int count;   // number of matching images
  int status;  // folder reachability (1 = reachable) for folders/film-rolls, else -1
} dt_collection_name_value_t;
 
GList *dt_collection_get_property_values(const dt_collection_properties_t property, const int rule);
void dt_collection_name_value_free(gpointer value);
 
void dt_collection_update_query(const dt_collection_t *collection, dt_collection_change_t query_change,
                                dt_collection_properties_t changed_property, GList *list);
 
void dt_collection_hint_message(const dt_collection_t *collection);
 
/* serialize and deserialize into a string. */
void dt_collection_deserialize(const char *buf);
int dt_collection_serialize(char *buf, int bufsize);
 
/* splits an input string into a number part and an optional operator part */
void dt_collection_split_operator_number(const gchar *input, char **number1, char **number2, char **op);
void dt_collection_split_operator_datetime(const gchar *input, char **number1, char **number2, char **op);
void dt_collection_split_operator_exposure(const gchar *input, char **number1, char **number2, char **op);
 
/* initialize memory table */
void dt_collection_memory_update();
 
void dt_selection_to_culling_mode();
void dt_culling_mode_to_selection();
 
#endif // DT_COMMON_COLLECTION_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