Initial checkin of Pika from heckimp

devel-docs/ui-framework.txt

@@ -0,0 +1,57 @@
+  PIKA UI Framework
+  =================
+
+This document describes how the PIKA UI framework functions and is
+implemented. Here, "UI framework" refers to the system that saves the
+UI layout between PIKA sessions, i.e. how docks, dockable dialogs etc
+are setup.
+
+
+  Key Classes
+  -----------
+
+PikaDockable      - Represents a dockable dialog.
+PikaDockbook      - A GtkNotebook of PikaDockables
+PikaDock          - A columns of PikaDockbooks
+PikaToolbox       - Subclasses PikaDock, contains the toolbox.
+                    Dockables are added at the bottom
+PikaMenuDock      - Subclasses PikaDock, contains dockables, should
+                    probably be merged with PikaDock. The name
+                    contains "menu" from the time when it hosted the
+                    Image Selection Menu that is now in the
+                    PikaDockWindow
+PikaDockColumns   - A set of PikaDocks arranged side by side.
+PikaDockWindow    - A toplevel window containing a PikaDockColumns.
+PikaImageWindow   - A toplevel window containing images and one
+                    PikaDockColumns to the left and to the right.
+PikaDialogFactory - A factory to create and position toplevel windows
+PikaSessionInfo   - Contains session info for one toplevel
+PikaUIConfigurer  - Configures the UI when switching between
+                    single-window and multi-window mode
+
+
+  PikaDialogFactory
+  -----------------
+
+The PikaDialogFactory can be considered to solve two distinct
+problems:
+
+1. Create widgets from text, in particular from text in sessionrc
+2. Session manage toplevel windows so their position is remembered
+   across PIKA sessions
+
+One possible design adjustment would be to have PikaWidgetFactory that
+takes care of 1), and then have PikaDialogFactory inherit from
+GtkWidgetFactory and implementing 2). PikaWidgetFactory could possibly
+use GtkBuilder.
+
+
+  sessionrc
+  ---------
+When PIKA starts, the sessionrc file is parsed. This step puts
+PikaSessionInfo:s into PikaDialogFactories. Later when dialogs are
+created, the dialog factory looks up existing session info entries. If
+one exists, it uses the session info to set e.g. the position of the
+created dialog. If it doesn't exist, it creates a new session info
+object for the dialog. When PIKA exists, the current session infos are
+then written back to sessionrc.