Start documenting the component manager.

git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@3442 57a11ea4-9604-0410-9ed3-97b8803252fd

src/doc/design/Makefile.am

@@ -1,14 +1,16 @@
 
 info_TEXINFOS = gnucash-design.texinfo
-gnucash_design_TEXINFOS = concept-index.texinfo \
+gnucash_design_TEXINFOS = \
-                          engine.texinfo \
+  component-manager.texinfo \
-                          fdl.texinfo \
+  concept-index.texinfo \
-                          function-index.texinfo \
+  engine.texinfo \
-                          intro.texinfo \
+  fdl.texinfo \
-                          register.texinfo \
+  function-index.texinfo \
-                          reports.texinfo \
+  intro.texinfo \
-                          top-level.texinfo \
+  register.texinfo \
-                          type-index.texinfo \
+  reports.texinfo \
-			  user-preferences.texinfo
+  top-level.texinfo \
+  type-index.texinfo \
+  user-preferences.texinfo
 
 CLEANFILES = gnucash-design.info gnucash-design.info-[0-9]*

src/doc/design/component-manager.texinfo

@@ -0,0 +1,138 @@
+@node Component Manager
+@chapter Component Manager
+@cindex Component Manager
+
+The Component Manager (hereafter referred to as the CM) is a framework
+for managing GUI objects in GnuCash. The CM provides several services.
+
+First, components may request automatic invocation of a 'refresh'
+handler that is called when a component may need to be redrawn. This
+mechanism is tied into the Engine's Event mechanism (@pxref{Events}),
+so that GUI components are notified when relevant Engine entities are
+created, modified, or destroyed.
+
+Components may also provide a 'close' handler so that the component
+may be closed through the CM API.
+
+The CM also provides the ability to search for existing components.
+
+
+@menu
+* Component Manager Introduction::  
+* Refresh Mechanism::           
+* Component Manager API::       
+@end menu
+
+
+@node Component Manager Introduction, Refresh Mechanism, Component Manager, Component Manager
+@section Introduction
+
+The GnuCash GUI must manage many different components (registers,
+reconcile windows, reports, graphs, main window, etc.).  Functions which
+need to be performed on or with GUI components include:
+
+
+@itemize
+
+@item Refreshing components. When Engine objects (Accounts,
+Transactions, Splits, etc.) are created, modified, or destroyed,
+the GUI components which reference those objects must be refreshed.
+
+@item Searching for existing components. For example, when the
+user chooses to 'Reconcile' an account with an existing reconcile
+dialog, that dialog should be raised to the top in lieu of creating
+a new reconcile dialog.
+
+@item Closing components.
+
+@end itemize
+
+
+In particular, keeping components updated in the face of changes in the
+Engine is a difficult problem. Requirements for handling refreshes
+include:
+
+@itemize
+
+@item The Engine should be able to inform user code when any account
+or transaction is changed (including changing their respective splits).
+This requirement is satisfied by the Engine Events.
+
+@item The refresh mechanism should not have specific knowledge of
+individual windows and other GUI elements. It should be easy to
+add new refreshable elements to the mechanism.
+
+@item Changes should be batchable with respect to refreshes, so that
+a sequence of changes only cause a refresh after the last change
+in a batch. Batching should be nestable, for coding simplicity.
+
+@item For very large batches of changes (loading files) we need to be
+able to turn off the mechanism entirely, perform the changes, and then
+perform a global, forced refresh. This should also be nestable.
+
+@item The Engine should not be managing GUI components.
+
+@item The refresh mechanism should be extendable to a multi-user
+situation in which changes can come from external components.
+
+@item Components should be able to specify which Engine entities
+can cause refreshes. This requirement avoids allows the implementation
+to avoid unnecessary refreshing.
+
+@end itemize
+
+
+@node Refresh Mechanism, Component Manager API, Component Manager Introduction, Component Manager
+@section Refresh Mechanism
+@cindex Refresh Mechanism
+
+The major design decisions of the CM relate to the refresh
+mechanism. The refresh mechanism consists of two parts, the Engine
+component and the GUI component. The Engine component is the
+Event mechanism (@pxref{Events}), while the GUI component is the
+Component Manager, which provide refresh functionality as well
+as other services.
+
+The diagram below illustrated the design of the GnuCash refresh
+mechanism.
+
+@example
+                            ----------
+                            |        |
+                            | Engine |
+                            |        |
+                            ----------
+                                /|\
+                                 |
+                                 |--- Events (from Engine)
+                                 |
+                                \|/
+                    -------------------------
+                    |                       |
+                    |   Component Manager   |
+                    |                       |
+                    -------------------------
+                   /            /|\          \     GUI Commands
+                  /              |            \--- including refresh
+                 /              \|/            \   invocations (from CM)
+-----------------         -----------------
+|               |         |               |
+| GUI Component |         | GUI Component |           ...
+|               |         |               |
+-----------------         -----------------
+@end example
+
+The top-level component is the Engine, which emits Events to the
+Component Manager. In fact, the Engine will send events to any
+registered handler, but in GnuCash, only the CM registers with
+the engine. All other GUI components register with the CM.
+
+The CM invokes the refresh handlers of GUI components based on the
+Engine events received the CM has received as well as information
+provided by the GUI components (such as which specific Engine
+entities the components are 'watching').
+
+
+@node Component Manager API,  , Refresh Mechanism, Component Manager
+@section Component Manager API
+@cindex Component Manager API

src/doc/design/engine.texinfo

@@ -1,4 +1,4 @@
-@node Engine
+@node Engine, Component Manager, Top Level, Top
 @chapter Engine
 @cindex The Engine
 

src/doc/design/gnucash-design.texinfo

@@ -66,6 +66,7 @@ of the @cite{GnuCash Design Document}, version @value{VERSION}.
 * Introduction::                
 * Top Level::                   
 * Engine::                      
+* Component Manager::           
 * Register::                    
 * Reports::                     
 * User Preferences::            
@@ -73,6 +74,7 @@ of the @cite{GnuCash Design Document}, version @value{VERSION}.
 * Data Type Index::             
 * Concept Index::               
 
+
 @detailmenu
  --- The Detailed Node Listing ---
 
@@ -138,6 +140,10 @@ GNCBooks
 
 * GNCBook API::                 
 
+Component Manager
+
+* Component Manager Introduction::  
+
 Register
 
 * Cells::                       
@@ -163,6 +169,7 @@ User Preferences
 @include intro.texinfo
 @include top-level.texinfo
 @include engine.texinfo
+@include component-manager.texinfo
 @include register.texinfo
 @include reports.texinfo
 @include user-preferences.texinfo

src/doc/design/register.texinfo

@@ -1,5 +1,6 @@
-@node Register, Reports, Engine, Top
+@node Register, Reports, Component Manager, Top
 @chapter Register
+@cindex Register
 
 The register is an infrastructure for building a modular matrix of cells
 in which each cell may be specialized to perform a particular function,