diff --git a/src/doc/design/Makefile.am b/src/doc/design/Makefile.am index e2dc393459..8ea79ebc4d 100644 --- a/src/doc/design/Makefile.am +++ b/src/doc/design/Makefile.am @@ -1,14 +1,16 @@ info_TEXINFOS = gnucash-design.texinfo -gnucash_design_TEXINFOS = concept-index.texinfo \ - engine.texinfo \ - fdl.texinfo \ - function-index.texinfo \ - intro.texinfo \ - register.texinfo \ - reports.texinfo \ - top-level.texinfo \ - type-index.texinfo \ - user-preferences.texinfo +gnucash_design_TEXINFOS = \ + component-manager.texinfo \ + concept-index.texinfo \ + engine.texinfo \ + fdl.texinfo \ + function-index.texinfo \ + intro.texinfo \ + register.texinfo \ + reports.texinfo \ + top-level.texinfo \ + type-index.texinfo \ + user-preferences.texinfo CLEANFILES = gnucash-design.info gnucash-design.info-[0-9]* diff --git a/src/doc/design/component-manager.texinfo b/src/doc/design/component-manager.texinfo new file mode 100644 index 0000000000..3b59d9c07c --- /dev/null +++ b/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 diff --git a/src/doc/design/engine.texinfo b/src/doc/design/engine.texinfo index 13741348f8..a95b2e57e5 100644 --- a/src/doc/design/engine.texinfo +++ b/src/doc/design/engine.texinfo @@ -1,4 +1,4 @@ -@node Engine +@node Engine, Component Manager, Top Level, Top @chapter Engine @cindex The Engine diff --git a/src/doc/design/gnucash-design.texinfo b/src/doc/design/gnucash-design.texinfo index b5a019bdd4..4bef002143 100644 --- a/src/doc/design/gnucash-design.texinfo +++ b/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 --- @@ -89,7 +91,7 @@ Engine * Accounts:: * Account Groups:: * GNCBooks:: -* Scrub:: +* Scrub:: Globally Unique Identifiers @@ -101,7 +103,7 @@ Globally Unique Identifiers Numeric Library -* Standard Numeric Arguments:: +* Standard Numeric Arguments:: * Creating Numeric Objects:: * Basic Arithmetic Operations:: * Numeric Comparisons and Predicates:: @@ -109,7 +111,7 @@ Numeric Library * Numeric Floating Point Conversion:: * Numeric String Conversion:: * Numeric Error Handling :: -* Numeric Example:: +* Numeric Example:: Key-Value Pair Frames @@ -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 diff --git a/src/doc/design/register.texinfo b/src/doc/design/register.texinfo index 3187298b47..def896805f 100644 --- a/src/doc/design/register.texinfo +++ b/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,