doc/diagrams.dox

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