[gimp] devel-docs: Add initial version of context.txt, explaining GimpContext

[Martin Nordholts <martinn src gnome org>]

commit 70d30207f04ac6a7d4e8c8eb957c6cfe43e6dcf0
Author: Martin Nordholts <martinn src gnome org>
Date:   Tue Jan 5 18:15:41 2010 +0100

    devel-docs: Add initial version of context.txt, explaining GimpContext

 devel-docs/contexts.txt |   64 +++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 64 insertions(+), 0 deletions(-)
---
diff --git a/devel-docs/contexts.txt b/devel-docs/contexts.txt
new file mode 100644
index 0000000..db6b3df
--- /dev/null
+++ b/devel-docs/contexts.txt
@@ -0,0 +1,64 @@
+contexts.txt
+============
+
+Introduction
+------------
+
+This file describes how the GimpContext's in GIMP are used.
+
+
+Overview
+--------
+
+One imporant 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 does 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()
+        |                |              |              |------------>|
+        |                |              |              |             |
+
+
+Parent/child relationships
+--------------------------
+
+TODO
+
+