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