PIKApp/devel-docs/contexts.txt

90 lines
3.8 KiB
Plaintext
Raw Normal View History

2023-09-26 00:35:21 +02:00
contexts.txt
============
Introduction
------------
This file describes how PikaContexts are used in PIKA.
Overview
--------
One important context is the so called "user context",
pika_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 PIKA. 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:
PikaContext PikaContext PikaItemTreeView,
PikaDisplayShell user PikaDockWindow dock window PikaLayerTreeView
| | | | |
focus event | | | |
------->| | | | |
| pika_context_set_display() | | |
|--------------->|----------+ | | |
| | | | | |
| pika_context_set_image() | | | |
| |<---------+ | | |
| | | | |
| | "image-changed" | |
| |------------->| | |
| | | pika_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:
PikaContext PikaItemTreeView
PikaDisplayShell user PikaLayerTreeView
| | |
focus event | |
------->| | |
| pika_context_set_display() |
|--------------->|----------+ |
| | | |
| pika_context_set_image() | |
| |<---------+ |
| | |
| | "image-changed" /
| | set_image()
| |------------->|
| | |
| | |
| | |
| | |
| | |
| | |
Parent/child relationships
--------------------------
TODO