1 /* 2 This file is part of darktable, 3 Copyright (C) 2010-2021 darktable developers. 4 5 darktable is free software: you can redistribute it and/or modify 6 it under the terms of the GNU General Public License as published by 7 the Free Software Foundation, either version 3 of the License, or 8 (at your option) any later version. 9 10 darktable is distributed in the hope that it will be useful, 11 but WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 GNU General Public License for more details. 14 15 You should have received a copy of the GNU General Public License 16 along with darktable. If not, see <http://www.gnu.org/licenses/>. 17 */ 18 19 #pragma once 20 21 #include <glib.h> 22 #include <sqlite3.h> 23 #include <stdint.h> 24 25 typedef struct dt_tag_t 26 { 27 guint id; 28 gchar *tag; 29 gchar *leave; 30 gchar *synonym; 31 guint count; 32 guint select; 33 gint flags; 34 } dt_tag_t; 35 36 typedef enum dt_tag_flags_t 37 { 38 DT_TF_NONE = 0, 39 DT_TF_CATEGORY = 1 << 0, // this tag (or path) is not a keyword to be exported 40 DT_TF_PRIVATE = 1 << 1, // this tag is private. Will be exported only on demand 41 DT_TF_ORDER_SET = 1 << 2, // set if the tag has got an images order 42 DT_TF_DESCENDING = 1 << 31, 43 } dt_tag_flags_t; 44 45 #define DT_TF_ALL (DT_TF_CATEGORY | DT_TF_PRIVATE | DT_TF_ORDER_SET) 46 47 typedef enum dt_tag_selection_t 48 { 49 DT_TS_NO_IMAGE = 0, // no selection or no tag not attached 50 DT_TS_SOME_IMAGES, // tag attached on some selected images 51 DT_TS_ALL_IMAGES // tag attached on all selected images 52 } dt_tag_selection_t; 53 54 /** creates a new tag, returns tagid \param[in] name the tag name. \param[in] tagid a pointer to tagid of new 55 * tag, this can be NULL \return false if failed to create a tag and indicates that tagid is invalid to use. 56 * \note If tag already exists the existing tag id is returned. */ 57 gboolean dt_tag_new(const char *name, guint *tagid); 58 59 /** creates a new tag, returns tagid \param[in] name the tag name. \param[in] tagid a pointer to tagid of new 60 * tag, this can be NULL \return false if failed to create a tag and indicates that tagid is invalid to use. 61 * \note If tag already exists the existing tag id is returned. This function will also raise a 62 * DT_SIGNAL_TAG_CHANGED signal if necessary, so keywords GUI can refresh. */ 63 gboolean dt_tag_new_from_gui(const char *name, guint *tagid); 64 65 // read/import tags from a txt file as written by Lightroom. returns the number of imported tags 66 // or -1 if an error occurred. 67 ssize_t dt_tag_import(const char *filename); 68 69 // export all tags to a txt file as written by Lightroom. returns the number of exported tags 70 // or -1 if an error occurred. 71 ssize_t dt_tag_export(const char *filename); 72 73 /** get the name of specified id */ 74 gchar *dt_tag_get_name(const guint tagid); 75 76 /** removes a tag from db and from assigned images. \param final TRUE actually performs the remove \return 77 * the amount of images affected. */ 78 guint dt_tag_remove(const guint tagid, gboolean final); 79 80 /** removes a list of tags from db and from assigned images. \return the number of tags deleted */ 81 guint dt_tag_remove_list(GList *tag_list); 82 83 /** set the name of specified id */ 84 void dt_tag_rename(const guint tagid, const gchar *new_tagname); 85 86 /** checks if tag exists. \param[in] name of tag to check. \return the id of found tag or -1 i not found. */ 87 gboolean dt_tag_exists(const char *name, guint *tagid); 88 89 /** attach a tag on images list. tagid id of tag to attach. img the list of image 90 * id to attach tag to */ 91 gboolean dt_tag_attach_images(const guint tagid, const GList *img, const gboolean undo_on); 92 /** attach a tag on images. tagid id of tag to attach. imgid the image 93 * id to attach tag to, if < 0 images to act on are used. */ 94 gboolean dt_tag_attach(const guint tagid, const gint imgid, const gboolean undo_on, const gboolean group_on); 95 96 /** check if a tag is attached to the given image */ 97 gboolean dt_is_tag_attached(const guint tagid, const gint imgid); 98 99 /** attach a list of tags on selected images. \param[in] tags a list of ids of tags. \param[in] imgid the 100 * image id to attach tag to, if < 0 selected images are used. \note If tag not exists it's created 101 * if clear_on TRUE the image tags are cleared before attaching the new ones*/ 102 gboolean dt_tag_set_tags(const GList *tags, const GList *img, const gboolean ignore_dt_tags, 103 const gboolean clear_on, const gboolean undo_on); 104 105 /** attach a list of tags on list of images. \param[in] tags a comma separated string of tags. \param[in] 106 * img the list of images to attach tag to. \note If tag does not exist, it's created.*/ 107 gboolean dt_tag_attach_string_list(const gchar *tags, const GList *img, const gboolean undo_on); 108 109 /** detach tag from images. \param[in] tagid of tag to detach. \param[in] img the list of image id to detach 110 * tag from */ 111 gboolean dt_tag_detach_images(const guint tagid, const GList *img, const gboolean undo_on); 112 /** detach tag from images. \param[in] tagid of tag to detach. \param[in] imgid the image id to detach 113 * tag from, if < 0 images to act on are used. */ 114 gboolean dt_tag_detach(const guint tagid, const gint imgid, const gboolean undo_on, const gboolean group_on); 115 116 /** detach tags from images that matches name, it is valid to use % to match tag */ 117 gboolean dt_tag_detach_by_string(const char *name, const gint imgid, const gboolean undo_on, 118 const gboolean group_on); 119 120 /** retrieves a list of tags of specified imgid \param[out] result a list of dt_tag_t, sorted by tag. */ 121 uint32_t dt_tag_get_attached(const gint imgid, GList **result, const gboolean ignore_dt_tags); 122 123 /** sort tags per name (including '|') or per count (desc) */ 124 GList *dt_sort_tag(GList *tags, gboolean byname); 125 126 /** get a list of tags, 127 * the difference to dt_tag_get_attached() is that this one splits at '|' and filters out the "darktable|" 128 * tags. */ 129 GList *dt_tag_get_list(gint imgid); 130 131 /** get a list of tags, 132 * the difference to dt_tag_get_list() is that this one checks option for exportation */ 133 GList *dt_tag_get_list_export(gint imgid, int32_t flags); 134 135 /** get a flat list of only hierarchical tags, 136 * the difference to dt_tag_get_attached() is that this one filters out the "darktable|" tags. */ 137 GList *dt_tag_get_hierarchical(gint imgid); 138 139 /** get a flat list of only hierarchical tags, 140 * the difference to dt_tag_get_hierarchical() is that this one checks option for exportation */ 141 GList *dt_tag_get_hierarchical_export(gint imgid, int32_t flags); 142 143 /** get a flat list of tags id attached to image id*/ 144 GList *dt_tag_get_tags(const gint imgid, const gboolean ignore_dt_tags); 145 146 /** get the subset of images that have a given tag attached */ 147 GList *dt_tag_get_images(const gint tagid); 148 149 /** get the subset of images from the given list that have a given tag attached */ 150 GList *dt_tag_get_images_from_list(const GList *img, const gint tagid); 151 152 /** retrieves a list of suggested tags matching keyword. \param[in] keyword the keyword to search \param[out] 153 * result a pointer to list populated with result. \return the count \note the limit of result is decided by 154 * conf value "xxx" */ 155 uint32_t dt_tag_get_suggestions(GList **result); 156 157 /** retrieves count of tagged images. \param[in] keyword the keyword to search \return 158 * the count \note the limit of result is decided by conf value "xxx" */ 159 void dt_tag_count_tags_images(const gchar *keyword, int *tag_count, int *img_count); 160 161 /** retrieves list of tags and tagged images. \param[in] keyword the keyword to search. \param[out] result pointers to list 162 * populated with result. \note the limit of result is decided by conf value "xxx" */ 163 void dt_tag_get_tags_images(const gchar *keyword, GList **tag_list, GList **img_list); 164 165 /** retrieves the list of tags matching keyword. \param[in] keyword the keyword to search \param[out] 166 * result a pointer to list populated with result. \return the count \note the limit of result is decided by 167 * conf value "xxx" */ 168 uint32_t dt_tag_get_with_usage(GList **result); 169 170 /** retrieves synonyms of the tag */ 171 gchar *dt_tag_get_synonyms(gint tagid); 172 173 /** sets synonyms of the tag */ 174 void dt_tag_set_synonyms(gint tagid, gchar *synonyms); 175 176 /** retrieves flags of the tag */ 177 gint dt_tag_get_flags(gint tagid); 178 179 /** sets flags of the tag */ 180 void dt_tag_set_flags(gint tagid, gint flags); 181 182 /** retrieves a list of recent tags used. \param[out] result a pointer to list populated with result. \return 183 * the count \note the limit of result is decided by conf value "xxx" */ 184 uint32_t dt_tag_get_recent_used(GList **result); 185 186 /** frees the memory of a result set. */ 187 void dt_tag_free_result(GList **result); 188 189 /** get number of selected images */ 190 uint32_t dt_selected_images_count(); 191 192 /** get number of images affected with that tag */ 193 uint32_t dt_tag_images_count(gint tagid); 194 195 /** retrieves the subtags of requested level for the requested category */ 196 char *dt_tag_get_subtags(const gint imgid, const char *category, const int level); 197 198 /** return the images order associated to that tag */ 199 gboolean dt_tag_get_tag_order_by_id(const uint32_t tagid, uint32_t *sort, 200 gboolean *descending); 201 202 /** save the images order on the tag */ 203 void dt_tag_set_tag_order_by_id(const uint32_t tagid, const uint32_t sort, 204 const gboolean descending); 205 206 /** return the tagid of that tag - follow tag sensitivity - return 0 if not found*/ 207 uint32_t dt_tag_get_tag_id_by_name(const char * const name); 208 209 /** init the darktable tags table */ 210 void dt_set_darktable_tags(); 211 212 // modelines: These editor modelines have been set for all relevant files by tools/update_modelines.sh 213 // vim: shiftwidth=2 expandtab tabstop=2 cindent 214 // kate: tab-indents: off; indent-width 2; replace-tabs on; indent-mode cstyle; remove-trailing-spaces modified; 215