doc/diagrams.c

   1 /*
   2  * Copyright (C) 2006 John Ellis
   3  * Copyright (C) 2008 - 2022 The Geeqie Team
   4  *
   5  * Author: Colin Clark
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License along
  18  * with this program; if not, write to the Free Software Foundation, Inc.,
  19  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  20  */
  21
  22 /**
  23  * @file
  24  * @brief Diagrams to be included in the Doxygen output
  25  *
  26  * The contents are diagrams to be included in the Doxygen output.
  27  * The .c file extension is so that Doxygen will process it.
  28  */
  29
  30 /**
  31  * @page diagrams Diagrams
  32  * @section metadata_write Metadata write sequence
  33  *
  34  * @startuml
  35  *
  36  * group metadata write sequence
  37  * start
  38  *
  39  * : write to file/sidecar = FALSE;
  40  * if (//Preferences / Metadata//\n **Step 1:**\n Save in image file or sidecar file) then (yes)
  41          * if (extension in //File Filters / File Types / Writable// list) then (yes)
  42                  * if (image file writable) then (yes)
  43                          * : write to file/sidecar = TRUE;
  44                          * : metadata_file = <image file>;
  45                  * else (no)
  46                          * : log warning;
  47                  * endif
  48          * else (no)
  49                  * if (extension in //File Filters / File Types / Sidecar Is Allowed// list) then (yes)
  50                          * if (sidecar file or folder writable) then (yes)
  51                                  * : write to file/sidecar = TRUE;
  52                                  * : metadata_file = <sidecar file>;
  53                          * else (no)
  54                                  * : log warning;
  55                          * endif
  56                  * else (no)
  57                  * endif
  58          * endif
  59  * else (no)
  60  * endif
  61  *
  62  * if (write to file/sidecar) then (yes)
  63  * else (no)
  64          * group If a metadata file already exists, use it
  65                  * start
  66                  * group Look in user defined option
  67                          * if (//Preferences / Metadata//\n **Step 2:**\n Save in sub-folder local to image folder) then (yes)
  68                                  * : metadata_file = \n<file_dir>/.metadata/<filename>.gq.xmp;
  69                          * else (no)
  70                                  * if (XDG_DATA_HOME defined) then (yes)
  71                                          * : metadata_file = \nXDG_DATA_HOME/geeqie/metadata/<file_path>/<file_name>.gq.xmp;
  72                                  * else (no)
  73                                          * : metadata_file = \nHOME/.local/share/geeqie/metadata/<file_path>/<file_name>.gq.xmp;
  74                                  * endif
  75                          * endif
  76                  * end group
  77                  *
  78                  * if (metadata_file exists) then (yes)
  79                  * else (no)
  80                          * group Ignore user defined option and try alternate
  81                                  * if (//Preferences / Metadata//\n **Step 2:**\n Save in sub-folder local to image) then (no)
  82                                          * : metadata_file = \n <file_dir>/.metadata/<filename>.gq.xmp;
  83                                  * else (yes)
  84                                          * if (XDG_DATA_HOME defined) then (yes)
  85                                                  * : metadata_file = \n XDG_DATA_HOME/geeqie/metadata/<file_path>/<file_name>.gq.xmp;
  86                                          * else (no)
  87                                                  * : metadata_file = \n HOME/.local/share/geeqie/metadata/<file_path>/<file_name>.gq.xmp;
  88                                          * endif
  89                                  * endif
  90                          * end group
  91                  * endif
  92                  *
  93                  * if (metadata_file exists) then (yes)
  94                  * else (no)
  95                          * group Try GQview legacy format
  96                                  * if (//Preferences / Metadata//\n **Step 2:**\n Save in sub-folder local to image folder) then (yes)
  97                                          * : metadata_file = \n<file_dir>/.metadata/<filename>.meta;
  98                                  * else (no)
  99                                          * if (XDG_DATA_HOME defined) then (yes)
 100                                                  * : metadata_file = \nXDG_DATA_HOME/geeqie/metadata/<file_path>/<file_name>.meta;
 101                                          * else (no)
 102                                                  * : metadata_file = \nHOME/.local/share/geeqie/metadata/<file_path>/<file_name>.meta;
 103                                          * endif
 104                                  * endif
 105                          * end group
 106                          *
 107                          * if (metadata_file exists) then (yes)
 108                          * else (no)
 109                                  * group Ignore user defined option and try alternate
 110                                          * if (//Preferences / Metadata//\n **Step 2:**\n Save in sub-folder local to image) then (no)
 111                                                  * : metadata_file = \n <file_dir>/.metadata/<filename>.meta;
 112                                          * else (yes)
 113                                                  * if (XDG_DATA_HOME defined) then (yes)
 114                                                          * : metadata_file = \n XDG_DATA_HOME/geeqie/metadata/<file_path>/<file_name>.meta;
 115                                                  * else (no)
 116                                                          * : metadata_file = \n HOME/.local/share/geeqie/metadata/<file_path>/<file_name>.meta;
 117                                                  * endif
 118                                          * endif
 119                                  * end group
 120                          * endif
 121                  * endif
 122          * end group
 123          *
 124          * if (metadata_file exists) then (yes)
 125          * else (no)
 126                  * group If no metadata file exists, use user defined option
 127                          * if (//Preferences / Metadata//\n **Step 2:**\n Save in sub-folder local to image folder) then (yes)
 128                                  * : metadata_file = \n<file_dir>/.metadata/<filename>.gq.xmp;
 129                          * else (no)
 130                                  * if (XDG_DATA_HOME defined) then (yes)
 131                                          * : metadata_file = \nXDG_DATA_HOME/geeqie/metadata/<file_path>/<file_name>.gq.xmp;
 132                                  * else (no)
 133                                          * : metadata_file = \nHOME/.local/share/geeqie/metadata/<file_path>/<file_name>.gq.xmp;
 134                                  * endif
 135                          * endif
 136                  * end group
 137          * endif
 138          *
 139          * if (metadata_file writable) then (yes)
 140          * else (no)
 141                  * if (XDG_DATA_HOME defined) then (yes)
 142                          * : metadata_file = \nXDG_DATA_HOME/geeqie/metadata/<file_path>/<file_name>.gq.xmp;
 143                  * else (no)
 144                  * : metadata_file = \nHOME/.local/share/geeqie/metadata/<file_path>/<file_name>.gq.xmp;
 145                  * endif
 146          * : Recursively create metadata_file_path\n if necessary;
 147          * endif
 148  * endif
 149  * : Write metadata;
 150  *
 151  * end group
 152  * @enduml
 153  */
 154   /**
 155   * @file
 156   * @ref metadata_write "Metadata write sequence"
 157   */
 158
 159
 160 /**
 161  * @page diagrams Diagrams
 162  * @section options_overview Options Overview
 163  *
 164  * #_ConfOptions  #_LayoutOptions
 165  *
 166  * @startuml
 167  *
 168  * object options.h
 169  * object typedefs.h
 170  *
 171  * options.h : ConfOptions
 172  * options.h : \n
 173  * options.h : Options applicable to **all** Layout Windows
 174  * options.h : These are in the <global> section of geeqierc.xml
 175  * options.h : Available to all modules via the global variable **options**
 176  * typedefs.h : LayoutOptions
 177  * typedefs.h : \n
 178  * typedefs.h : Options applicable to **each** Layout Window
 179  * typedefs.h : These are in the <layout> section of geeqierc.xml
 180  * typedefs.h : There is one <layout> section for each Layout Window displayed
 181  * typedefs.h : Available via **<layout_window>->options**
 182  *
 183  * @enduml
 184  */
 185
 186 /**
 187  * @page diagrams Diagrams
 188  * @section options_diagrams_main Options - New Window From Main
 189  * #main
 190  * #init_options
 191  * #layout_new_from_default
 192  * #load_config_from_file
 193  * #load_options
 194  * #setup_default_options
 195  *
 196  * @startuml
 197  * group main.c
 198  * start
 199  * group options.c
 200  * : **init_options()**
 201  *
 202  * Set **options** = ConfOptions from hard-coded init values;
 203  * end group
 204  *
 205  * group options.c
 206  * : **setup_default_options()**
 207  *
 208  * set hard-coded ConfOptions:
 209  *
 210  * bookmarks:
 211  * * dot dir
 212  * * Home
 213  * * Desktop
 214  * * Collections
 215  * safe delete path
 216  * OSD template string
 217  * sidecar extensions
 218  * shell path and options
 219  * marks tooltips
 220  * help search engine;
 221  * end group
 222  *
 223  * if (first entry
 224  * or
 225  * --new-instance) then (yes)
 226  * group options.c
 227  * : **load_options()**
 228  * ;
 229  *
 230  * split
 231  * : GQ_SYSTEM_WIDE_DIR
 232  * /geeqierc.xml;
 233  * split again
 234  * : XDG_CONFIG_HOME
 235  * /geeqierc.xml;
 236  * split again
 237  * : HOME
 238  * /.geeqie/geeqierc.xml;
 239  * end split
 240  *
 241  * group rcfile.c
 242  * : **load_config_from_file()**
 243  *
 244  * set  **options** from file
 245  * and all <layout window>->options  in file;
 246  * end group
 247  *
 248  * end group
 249  *
 250  * if (broken config. file
 251  * or no config file
 252  * or no layout section loaded
 253  * (i.e. session not saved)) then (yes)
 254  * group layout.c
 255  * : **layout_new_from_default()**;
 256  * if (default.xml exists) then (yes)
 257  * : Load user-saved
 258  *  layout_window default options
 259  *  from default.xml file;
 260  * else (no)
 261  * : Load hard-coded
 262  *  layout_window default options;
 263  * endif
 264  * end group
 265  * endif
 266  *
 267  * else (no)
 268  * : Send --new-window request to remote
 269  *  No return to this point
 270  *  This instance terminates;
 271  * stop
 272  * endif
 273  *
 274  * : Enter gtk main loop;
 275  *
 276  * end group
 277  * @enduml
 278  */
 279
 280 /**
 281  * @page diagrams Diagrams
 282  * @section options_diagrams_remote Options - New Window From Remote
 283  * #layout_new_from_default
 284  * @startuml
 285  *
 286  * group remote.c
 287  * start
 288  * group layout.c
 289  * : **layout_new_from_default()**;
 290  * if (default.xml exists) then (yes)
 291  * : Load user-saved
 292  *  layout_window default options
 293  *  from default.xml file;
 294  * else (no)
 295  * : Load hard-coded
 296  *  layout_window default options;
 297  * endif
 298  * end group
 299  * : set path from PWD;
 300  * @enduml
 301  */
 302
 303 /**
 304  * @page diagrams Diagrams
 305  * @section options_diagrams_menu Options - New Window From Menu
 306  * #layout_menu_new_window_cb
 307  * #layout_menu_window_from_current_cb
 308  * #layout_new_from_default
 309  * @startuml
 310  *
 311  * group layout_util.c
 312  * start
 313  *
 314  * split
 315  * : default;
 316  * group layout.c
 317  * : **layout_new_from_default()**;
 318  * if (default.xml exists) then (yes)
 319  * : Load user-saved
 320  *  layout_window default options
 321  *  from default.xml file;
 322  * else (no)
 323  * : Load hard-coded
 324  *  layout_window default options;
 325  * endif
 326  * end group
 327  *
 328  * split again
 329  * : from current
 330  *
 331  * **layout_menu_window_from_current_cb()**
 332  * copy layout_window options
 333  * from current window;
 334  *
 335  * split again
 336  * : named
 337  *
 338  * **layout_menu_new_window_cb()**
 339  * load layout_window options
 340  * from saved xml file list;
 341  * end split
 342  *
 343  * end group
 344  * @enduml
 345  */
 346   /**
 347   * @file
 348   * @ref options_overview "Options Overview"
 349   */
 350
 351 /**
 352  * @page diagrams Diagrams
 353  * @section image_load_overview Image Load Overview
 354  * @startuml
 355  * object image_change
 356  * object image_change_complete
 357  * object image_load_begin
 358  * object image_loader_start
 359  * object image_loader_start_thread
 360  * object image_loader_setup_source
 361  * object image_loader_thread_run
 362  * object image_loader_begin
 363  * object image_loader_setuploader
 364  * circle "il->memory_mapped"
 365  * object exif_get_preview_
 366  * object exif_get_preview
 367  * object libraw_get_preview
 368  *
 369  * image_change : image.c
 370  * image_change_complete : image.c
 371  * image_load_begin : image.c
 372  * image_loader_start : image_load.c
 373  * image_loader_start_thread : image_load.c
 374  * image_loader_thread_run : image_load.c
 375  * image_loader_begin : image_load.c
 376  * image_loader_setuploader : image_load.c
 377  * image_loader_setuploader : -
 378  * image_loader_setuploader : Select backend using magic
 379  * image_loader_setup_source : image_load.c
 380  * exif_get_preview : exiv2.cc
 381  * exif_get_preview : EXIV2_TEST_VERSION(0,17,90)
 382  * exif_get_preview_ : exif.c
 383  * exif_get_preview_ : -
 384  * exif_get_preview_ : If exiv2 not installed
 385  * libraw_get_preview : image_load_libraw.c
 386  *
 387  * image_change --> image_change_complete
 388  * image_change_complete --> image_load_begin
 389  * image_load_begin --> image_loader_start
 390  * image_loader_start --> image_loader_start_thread
 391  * image_loader_start_thread --> image_loader_thread_run
 392  * image_loader_start_thread --> image_loader_setup_source
 393  * image_loader_setup_source --> exif_get_preview_
 394  * image_loader_setup_source --> exif_get_preview
 395  * image_loader_setup_source --> libraw_get_preview : Try libraw if exiv2 fails
 396  * exif_get_preview_ ..> "il->memory_mapped"
 397  * exif_get_preview ..> "il->memory_mapped"
 398  * libraw_get_preview ..> "il->memory_mapped"
 399  * image_loader_thread_run --> image_loader_begin
 400  * image_loader_begin --> image_loader_setuploader
 401  * "il->memory_mapped" ..> image_loader_setuploader
 402  * note left of "il->memory_mapped" : Points to first byte of embedded jpeg (#FFD8)\n if preview found, otherwise to first byte of file
 403  * @enduml
 404  */
 405  /**
 406   * @file
 407   * @ref image_load_overview "Image Load Overview"
 408   */
 409
 410 /**
 411  * @page diagrams Diagrams
 412  * @section duplicates_data_layout Duplicates Data Layout
 413  *
 414  * #_DupeWindow  #_DupeItem #_DupeMatch
 415  *
 416  * @startuml
 417  *
 418  * database DupeWindow [
 419  * <b>DupeWindow->list</b>
 420  * ====
 421  * DupeItem
 422  * ----
 423  * DupeItem
 424  * ----
 425  * DupeItem
 426  * ----
 427  * .
 428  * .
 429  * .
 430  * ]
 431  * note left
 432  * One entry for each file
 433  * dropped onto the dupes window
 434  * end note
 435  *
 436  * card DupeItem [
 437  * <b>DupeItem</b>
 438  * (parent)
 439  * ====
 440  * .
 441  * .
 442  * .
 443  * ----
 444  * fd
 445  * ----
 446  * group (list)
 447  * ----
 448  * group_rank
 449  * ----
 450  * .
 451  * .
 452  * .
 453  * ]
 454  * note right
 455  * group_rank: (sum of all child ranks) / n
 456  * end note
 457  *
 458  * database group [
 459  * <b>group (list)</b>
 460  * (children)
 461  * ====
 462  * DupeMatch
 463  * ----
 464  * DupeMatch
 465  * ----
 466  * DupeMatch
 467  * ----
 468  * .
 469  * .
 470  * .
 471  * ]
 472  * note left
 473  * One entry for each file
 474  * matching parent
 475  * end note
 476  *
 477  * card DupeMatch [
 478  * <b>DupeMatch</b>
 479  * ====
 480  * DupeItem
 481  * ----
 482  * rank
 483  * ----
 484  * ]
 485  *
 486  * DupeWindow -r-> DupeItem
 487  * group -r-> DupeMatch
 488  * DupeItem --> group
 489  * @enduml
 490  */