common/tags.h

Go to the documentation of this file.

/*
    This file is part of darktable,
    Copyright (C) 2010-2011 Henrik Andersson.
    Copyright (C) 2010-2012 johannes hanika.
    Copyright (C) 2010 Pascal de Bruijn.
    Copyright (C) 2012 Ivan Tarozzi.
    Copyright (C) 2012 José Carlos García Sogo.
    Copyright (C) 2012 Richard Wonka.
    Copyright (C) 2012-2013 Simon Spannagel.
    Copyright (C) 2012, 2014, 2016-2017 Tobias Ellinghaus.
    Copyright (C) 2013 Dennis Gnad.
    Copyright (C) 2013 Jérémy Rosen.
    Copyright (C) 2016 Roman Lebedev.
    Copyright (C) 2017, 2019, 2021 luzpaz.
    Copyright (C) 2019 Edgardo Hoszowski.
    Copyright (C) 2019-2021 Philippe Weyland.
    Copyright (C) 2020 Aldric Renaudin.
    Copyright (C) 2020-2021 Pascal Obry.
    Copyright (C) 2021 Hubert Kowalski.
    Copyright (C) 2022 Martin Bařinka.
    Copyright (C) 2022 Miloš Komarčević.
    Copyright (C) 2025 Alynx Zhou.
    Copyright (C) 2025-2026 Aurélien PIERRE.
    
    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/>.
*/
 
#pragma once
 
#include <glib.h>
#include <sqlite3.h>
#include <stdint.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
typedef struct dt_tag_t
{
  guint id;
  gchar *tag;
  gchar *leave;
  gchar *synonym;
  guint count;
  guint select;
  gint flags;
} dt_tag_t;
 
typedef enum dt_tag_flags_t
{
  DT_TF_NONE        = 0,
  DT_TF_CATEGORY    = 1 << 0, // this tag (or path) is not a keyword to be exported
  DT_TF_PRIVATE     = 1 << 1, // this tag is private. Will be exported only on demand
  DT_TF_ORDER_SET   = 1 << 2, // set if the tag has got an images order
  DT_TF_DESCENDING  = 1U << 31,
} dt_tag_flags_t;
 
#define DT_TF_ALL (DT_TF_CATEGORY | DT_TF_PRIVATE | DT_TF_ORDER_SET)
 
typedef enum dt_tag_selection_t
{
  DT_TS_NO_IMAGE = 0,   // no selection or no tag not attached
  DT_TS_SOME_IMAGES,    // tag attached on some selected images
  DT_TS_ALL_IMAGES      // tag attached on all selected images
} dt_tag_selection_t;
 
gboolean dt_tag_new(const char *name, guint *tagid);
 
gboolean dt_tag_new_from_gui(const char *name, guint *tagid);
 
// read/import tags from a txt file as written by Lightroom. returns the number of imported tags
// or -1 if an error occurred.
ssize_t dt_tag_import(const char *filename);
 
// export all tags to a txt file as written by Lightroom. returns the number of exported tags
// or -1 if an error occurred.
ssize_t dt_tag_export(const char *filename);
 
gchar *dt_tag_get_name(const guint tagid);
 
guint dt_tag_remove(const guint tagid, gboolean final);
 
guint dt_tag_remove_list(GList *tag_list);
 
void dt_tag_rename(const guint tagid, const gchar *new_tagname);
 
gboolean dt_tag_exists(const char *name, guint *tagid);
 
gboolean dt_tag_attach_images(const guint tagid, const GList *img, const gboolean undo_on);
gboolean dt_tag_attach(const guint tagid, const int32_t imgid, const gboolean undo_on, const gboolean group_on);
 
gboolean dt_is_tag_attached(const guint tagid, const int32_t imgid);
 
gboolean dt_tag_set_tags(const GList *tags, const GList *img, const gboolean ignore_dt_tags,
                         const gboolean clear_on, const gboolean undo_on);
 
gboolean dt_tag_attach_string_list(const gchar *tags, const GList *img, const gboolean undo_on);
 
gboolean dt_tag_detach_images(const guint tagid, const GList *img, const gboolean undo_on);
gboolean dt_tag_detach(const guint tagid, const int32_t imgid, const gboolean undo_on, const gboolean group_on);
 
gboolean dt_tag_detach_by_string(const char *name, const int32_t imgid, const gboolean undo_on,
                                 const gboolean group_on);
 
uint32_t dt_tag_get_attached(const int32_t imgid, GList **result, const gboolean ignore_dt_tags);
 
GList *dt_sort_tag(GList *tags, gboolean byname);
 
GList *dt_tag_get_list(int32_t imgid);
 
GList *dt_tag_get_list_export(int32_t imgid, int32_t flags);
 
GList *dt_tag_get_hierarchical(int32_t imgid);
 
GList *dt_tag_get_hierarchical_export(int32_t imgid, int32_t flags);
 
GList *dt_tag_get_tags(const int32_t imgid, const gboolean ignore_dt_tags);
 
GList *dt_tag_get_images(const gint tagid);
 
GList *dt_tag_get_images_from_list(const GList *img, const gint tagid);
 
uint32_t dt_tag_get_suggestions(GList **result);
 
void dt_tag_count_tags_images(const gchar *keyword, int *tag_count, int *img_count);
 
void dt_tag_get_tags_images(const gchar *keyword, GList **tag_list, GList **img_list);
 
uint32_t dt_tag_get_with_usage(GList **result);
 
gchar *dt_tag_get_synonyms(gint tagid);
 
void dt_tag_set_synonyms(gint tagid, gchar *synonyms);
 
gint dt_tag_get_flags(gint tagid);
 
void dt_tag_set_flags(gint tagid, gint flags);
 
uint32_t dt_tag_get_recent_used(GList **result);
 
void dt_tag_free_result(GList **result);
 
uint32_t dt_tag_images_count(gint tagid);
 
char *dt_tag_get_subtags(const int32_t imgid, const char *category, const int level);
 
gboolean dt_tag_get_tag_order_by_id(const uint32_t tagid, uint32_t *sort,
                                          gboolean *descending);
 
void dt_tag_set_tag_order_by_id(const uint32_t tagid, const uint32_t sort,
                                const gboolean descending);
 
uint32_t dt_tag_get_tag_id_by_name(const char * const name);
 
void dt_set_darktable_tags();
 
void dt_tags_cleanup(void);
 
#ifdef __cplusplus
}
#endif
 
// 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