[gimp] devel-docs: add specifications for the various locks behavior.

[Jehan <jehanp src gnome org>]

commit 61a0d9729253366e64f2cca81f0bf81b6428210e
Author: Jehan <jehan girinstud io>
Date:   Tue Feb 15 22:31:46 2022 +0100

    devel-docs: add specifications for the various locks behavior.
    
    As I review and tweak various aspects of GIMP UI, I also write down
    specifications for these subparts. Here is one for the locks behaviors.
    
    We worked on these specifications with Aryeom and tried to make the most
    useful and also somehow obvious logics for these locks, in particular
    the cases when applied to layer groups which can have wider ranges of
    meaning (on leaf items, it is much simpler). The various previous
    commits are implemented based on these specifications.

 devel-docs/README.md               |   7 ++
 devel-docs/specifications/locks.md | 162 +++++++++++++++++++++++++++++++++++++
 2 files changed, 169 insertions(+)
---
diff --git a/devel-docs/README.md b/devel-docs/README.md
index 0788277163..b027034c17 100644
--- a/devel-docs/README.md
+++ b/devel-docs/README.md
@@ -478,6 +478,13 @@ presentation of an artwork but for the work-in-progress processus.
 
 Developers are welcome to read the [specifications of XCF](specifications/xcf.txt).
 
+#### Locks
+
+Items in an image can be locked in various ways to prevent different
+types of edits.
+
+This is further explained in [the specifications of locks](specifications/locks.md).
+
 #### UI Framework
 
 GIMP has an evolved GUI framework, with a toolbox, dockables, menus…
diff --git a/devel-docs/specifications/locks.md b/devel-docs/specifications/locks.md
new file mode 100644
index 0000000000..23d888e44a
--- /dev/null
+++ b/devel-docs/specifications/locks.md
@@ -0,0 +1,162 @@
+This file details the logic for item locks (on layers, channels, paths,
+etc.)
+
+[TOC]
+
+## The 4 types of locks
+### Lock pixels
+
+Locking pixels means you cannot change any value in any of the channels
+of the image. In other words, you cannot paint, erase, apply any
+filters, neither can you apply most transformations.
+
+The only transformation which you can apply is moving the whole layer at
+once (not moving a selection contents), because then you only change the
+offsets. The contents of each channel stay the same.
+
+### Lock position
+
+Locking position is the opposite of the "Lock pixels" as you can do
+anything on your item except moving it, i.e. changing its offsets.
+
+### Lock alpha
+
+Locking alpha is in a way a subcase of "Lock pixels" as the only channel
+which cannot change is the alpha channel, i.e. how transparent is each
+pixel. You can still change the colors of pixels, but not their
+transparency. In other words, if you paint over a layer with "Lock
+alpha", this would only affect the color.
+
+This use case can sometimes be frustrating/confusing if you paint over
+full transparent pixels as it would look it's not working, yet you would
+get neither statusbar error nor blinking locks to explain why you see no
+changes on your layer.
+
+This lock is useless over an item with no alpha channel, though it is
+currently still allowed to set such a lock. It just does nothing useful.
+
+Note that you can still change the opacity of the item as a whole
+through the Opacity slider (for instance in Layers or Channels
+dockables) or through actions affecting the layer's opacity. It's only
+individual pixel alpha values which are locked.
+
+### Lock visibility
+
+Locking visibility means you cannot change the item's visibility
+(typically the "eye" icon on dockables).
+
+This is especially useful for when you [shift-click or
+alt-click](#exclusive-visibility-locks-switch) the eye icons to
+massively toggle item visibility, yet you want to exclude some items.
+For instance, say you have a background you want to always show and
+several foreground object you want to conditionally show alone or
+together. You could lock the background to keep it always visible and
+shift-click foreground objects.
+
+## Effects on layer groups
+
+Layers in particular can be grouped in "Layer groups". Though the effect
+of locks is obvious on non-group items, we tried to specify their
+behaviour when set on layer groups to be the most useful and also
+hopefully expected possible.
+
+Below are what the effects are for various locks.
+
+### Lock pixels and alpha
+
+Since it involves painting, it means nothing on layer groups as you
+can't paint on them. There are 2 exceptions:
+
+#### Layer group masks
+
+A layer group can have a mask. A "Lock pixels" would prevent from
+drawing in it. "Lock alpha" is meaningless there as masks don't have
+alpha channels (well they are kind of separate alpha value themselves,
+but as said, we use the "Lock pixels" to block this type of editing).
+
+#### Child layers
+
+These 2 locks when set on a group apply on all children. In other words,
+you can lock painting and drawing on many layers organized in groups by
+locking an ancestor.
+
+### Lock position
+
+Moving the group as a whole is equivalent to moving each and every of
+its children layers (recursively if there are sub-groups). Locking the
+layer group forbid this.
+
+Locking a group also forbid moving any child layer individually, as do
+"Lock pixels" and "Lock alpha".
+
+Note that locking the position of a child layer also prevents the whole
+group contents to be moved.
+
+So "Lock position" is really working both ways: any lock in the tree
+prevents the whole direct genealogy of layers to be moved. Sister layers
+are fine though.
+
+### Lock visibility
+
+Locking a layer group visibility has the exact semantic as locking a
+non-group layer since this is the only feature which is actually
+normally applicable to layer groups.
+
+Also it means that unlike all other lock features, locking the
+visibility of the layer group does not forbid changing visibility of a
+child layer.
+
+## Layer mask
+
+The layer mask is also its own particular case. Right now, the "Lock
+alpha" and "Lock visibility" don't affect them (masks are somehow their
+own alpha channel, but in the same time, we use "Lock pixels" to forbid
+painting; as for visibility, they have their own feature for this).
+
+"Lock pixels" prevents from painting in a mask.
+
+Note that both "Lock pixels" and "Lock position" prevent from moving a
+mask. Indeed masks dimensions are currently tied to their associated
+layer (or layer group) dimensions. It means than moving a mask does not
+just change the offset. You actually also delete some of the mask
+pixels/data and create new ones. Therefore moving changes the contents
+of the mask, which is why "Lock pixels" also prevent moving the mask.
+
+## Exclusive visibility/locks switch
+
+GIMP provides a way to massively toggles visibility and locks.
+
+### Exclusive switch on same level
+
+When `Shift-clicking` either a visibility icon or a lock icon, all other
+visibility or locks respectively on the same level will be switched OFF
+(leaving only the clicked switch ON). `Shift-clicking` again, all
+visibility or locks on same level will be back on.
+
+Say the state is:
+
+```
+* Layer 1
+* Layer group
+  * Layer 2
+  * Layer 3
+  * Layer 4
+* Layer 5
+```
+
+Then `Shift-click` the eye icon of Layer 3: Layer 2 and Layer 4's
+visibility will be turned OFF. Shift-click again and it goes back to
+initial state.
+
+### Exclusive switch of selected items
+
+When `Alt-clicking` a visibility or lock icon, the same happens as
+`Shift-click` except among selected items. The level in the item tree
+doesn't matter.
+
+### Exclusive visibility switch with a "Lock visibility" set
+
+If any "Lock visibility" is set on an item, its visibility status won't
+be switched along other items when `Shift-clicking` or `Alt-clicking`.
+Being able to exclude some items from such massive switch is one of the
+main use case of the "Lock visibility".