devel-docs/tagging.txt

   1 =============================================================
   2 How does resource tagging in Gimp work?
   3 =============================================================
   4
   5
   6 GimpTagged
   7
   8 Tagging is not limited to a concrete class hierarchy, but any class
   9 implementing the GimpTagged interface can be tagged. In addition to
  10 methods for adding/removing/enumerating tags it also requires
  11 GimpTagged objects to identify themselves:
  12
  13 * gimp_tagged_get_identifier: used to get a unique identifier of a
  14 GimpTagged object. For objects which are stored in a file it will
  15 usually be a filename.
  16
  17 * gimp_tagged_get_checksum: the identifier mentioned above has the problem
  18 that it can change during sessions (for example, user moves or renames
  19 a resource file). Therefore, there needs to be a way to get another
  20 identifier from the data of the tagged object, so that tags stored between
  21 session can be remapped properly.
  22
  23
  24 GimpTag
  25
  26 Tags are represented by a GimpTag object. There are no limitations for
  27 tag names except that they cannot contain a selected set of terminal
  28 punctuation characters (used to separate tags), leading or trailing
  29 whitespace and cannot begin with a reserved prefix for internal tags
  30 ('gimp:'). These conditions are enforced when creating a tag object from a
  31 tag string. The only reason for tag creation to fail is if there are
  32 no characters left after trying to fix a tag according to the
  33 rules above. Tag names are displayed as the user typed them (case
  34 sensitive), but tag comparison is done case-insensitively.
  35
  36 Tags are immutable, i.e. when a tag is created with one name string, it
  37 cannot be changed, but a new tag has to be created instead.
  38
  39 There are methods provided for convenient use with glib, a comparison
  40 function which can be used to sort tag lists and functions for storing
  41 tags in a GHashTable.
  42
  43
  44 GimpTagCache
  45
  46 Between sessions, tags assigned to objects are stored in a cache
  47 file. The cache file is a simple XML file, which lists all resources and
  48 tags which are added to them. Resources which have no tags assigned
  49 are listed here too, so that when we check the cache we know that they
  50 have no tags assigned instead of trying to find out if the resource file
  51 has been renamed.
  52
  53 When the session ends, a list of all resources and their tags
  54 is constructed. Resources which were not loaded during this session,
  55 but had tags assigned are also added to the list (they are saved
  56 because they could be useful in the next session, for example, when
  57 a temporarily disconnected network directory is reconnected). The list
  58 is then written to a tag cache file in the user's home directory.
  59
  60 When the session starts, the previously saved resource and tag mapping has to
  61 be loaded and assigned to GimpTagged objects. First the tag cache is
  62 loaded from file, and then containers are added (GimpContainer objects
  63 which contain items implementing the GimpTagged interface). After that,
  64 loaded resources are assigned tags:
  65
  66   If a resource identifier matches an identifier in the cache,
  67     corresponding tags are assigned to the GimpTagged object.
  68   Else, if the identifier is not found in the tag cache,
  69     an attempt is made to check if the resource file has been
  70     moved/renamed. In such case the checksum is used to match the
  71     GimpTagged object with all of the records in the tag cache.
  72     If a match is found,
  73       the identifier is updated in the tag cache.
  74     Otherwise,
  75       the loaded GimpTagged object is considered to be a newly
  76       added resource.
  77
  78
  79 GimpFilteredContainer
  80
  81 A GimpFilteredContainer is a "view" (representation) of a
  82 GimpContainer. It is related to tagging in that it can be used to
  83 filter a GimpContainer to contain only GimpTagged objects which have
  84 certain tags assigned. It is automatically updated with any changes in
  85 the GimpContainer it wraps. However, items should not be added or removed
  86 from this container manually as changes do not affect the original
  87 container and would be lost when the GimpFilteredContainer is
  88 updated. Instead, the contents should be changed by setting a tag list
  89 which would be used to filter GimpTagged objects containing all of the
  90 given GimpTags.
  91
  92 GimpFilteredContainer can use any GimpContainer as a source
  93 container. Therefore, it is possible to use the decorator design pattern
  94 to implement additional container views, such as a view combining items
  95 from multiple containers.
  96
  97
  98 GimpTagEntry widget
  99
 100 The GimpTagEntry widget extends GtkEntry and is used to either assign or
 101 query tags depending on the selected mode. The widget support various
 102 usability features:
 103
 104  * Jellybeans: When a tag is entered and confirmed by either separator,
 105    pressing return or otherwise, it becomes a jellybean, i.e. a single
 106    unit, not a bunch of characters. Navigating in a GimpTagEntry,
 107    deleting tags, etc. can be performed much faster. However, while a tag
 108    is just being entered (not yet confirmed), all actions operate on
 109    characters as usual.
 110
 111  * Custom auto completion is implemented in the GimpTagEntry widget which
 112    allows to complete tags in the middle of a tag list, doesn't offer
 113    already completed tags, tab cycles all possible completions, etc.
 114
 115  * If the GimpTagEntry is empty and unused it displays a description for
 116    the user regarding its purpose.
 117
 118 When operating in tag assignment mode, tags are assigned only when
 119 the user hits the return key.
 120
 121 When operating in tag query mode, the given GimpFilteredContainer is
 122 filtered as the user types. The GimpTagEntry also remembers recently used
 123 configurations, which can be cycled using up and down arrow keys.
 124
 125
 126 GimpComboTagEntry widget
 127
 128 The GimpComboTagEntry widget extends GimpTagEntry and adds the ability to pick
 129 tags from a menu-like list (using the GimpTagPopup widget).
 130
 131
 132 GimpTagPopup widget
 133
 134 The GimpTagPopup widget is used as a tag list menu from the GimpComboTagEntry
 135 widget. It is not designed to be used with any other widget.
 136
 137 GimpTagPopup has many visual and behavioral similarities to GtkMenu.
 138 In particular, it uses menu-like scrolling.
 139
 140 GimpTagPopup implements various usability features, some of which are:
 141
 142  * Tags which would result in an empty selection of resources are made
 143    insensitive.
 144
 145  * Closing either with the keyboard or by clicking outside the popup area.
 146
 147  * Underlining of highlighted (hovered) tags.
 148