summaryrefslogtreecommitdiffstats
path: root/devel-docs/contexts.txt
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--devel-docs/contexts.txt89
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