Adding upstream version 2.10.34.upstream/2.10.34upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 89 insertions, 0 deletions

diff --git a/devel-docs/contexts.txt b/devel-docs/contexts.txt
new file mode 100644
index 0000000..014320c
--- /dev/null
+++ b/devel-docs/contexts.txt
@@ -0,0 +1,89 @@
+contexts.txt
+============
+
+Introduction
+------------
+
+This file describes how GimpContexts are used in GIMP.
+
+
+Overview
+--------
+
+One important context is the so called "user context",
+gimp_get_user_context(). This context keeps track on what image the
+user currently has active, for example. Dock windows have their own
+context which does not necessarily mirror the user context. A dock
+window can be set to show information for a specific image. Plug-ins
+also have their own context.
+
+
+Communication between contexts
+------------------------------
+
+So how do the various contexts synchronize and propagate changes?
+This is most easily explained by a sequence diagram. Let's say there
+are two image windows with different images opened in GIMP. Call them
+A and B. Let's say A is currently active. When the user activates B,
+this is the sequence of events from the focus event to the layers
+dockable have been updated with the new image. To understand the
+diagram, you have to know that the dock window has connected signal
+handlers to image changes in the user context (through a dialog
+factory getter), and the layer dockable have connected a signal
+handler to image changes in the dock window context. The sequence of
+events is as follows:
+
+                    GimpContext                  GimpContext   GimpItemTreeView,
+ GimpDisplayShell      user      GimpDockWindow  dock window   GimpLayerTreeView
+
+        |                |              |              |             |
+ focus event             |              |              |             |
+------->|                |              |              |             |
+        |  gimp_context_set_display()   |              |             |
+        |--------------->|----------+   |              |             |
+        |                |          |   |              |             |
+        |  gimp_context_set_image() |   |              |             |
+        |                |<---------+   |              |             |
+        |                |              |              |             |
+        |                |    "image-changed"          |             |
+        |                |------------->|              |             |
+        |                |              |  gimp_context_set_image()  |
+        |                |              |------------->|             |
+        |                |              |              |      "image-changed" /
+        |                |              |              |         set_image()
+        |                |              |              |------------>|
+        |                |              |              |             |
+
+In single-window mode, the dockables listen directly to the user
+context. When switching between single-window and multi-window modes,
+the dockables are updated with their new context, just as when moving
+a dockable between different dock windows and thus also different
+contexts. The sequence diagram for single-window mode is:
+
+                    GimpContext  GimpItemTreeView
+ GimpDisplayShell      user      GimpLayerTreeView
+
+        |                |              |
+ focus event             |              |
+------->|                |              |
+        |  gimp_context_set_display()   |
+        |--------------->|----------+   |
+        |                |          |   |
+        |  gimp_context_set_image() |   |
+        |                |<---------+   |
+        |                |              |
+        |                |    "image-changed" /
+        |                |       set_image()
+        |                |------------->|
+        |                |              |
+        |                |              |
+        |                |              |
+        |                |              |
+        |                |              |
+        |                |              |
+
+
+Parent/child relationships
+--------------------------
+
+TODO