r23344 - gnucash/trunk/src/doc/design - Rename .texinfo files to .texi to get rid of the autogen.sh warning.
Frank H. Ellenberger
fell at code.gnucash.org
Sun Oct 27 21:02:54 EDT 2013
Author: fell
Date: 2013-10-27 21:02:53 -0400 (Sun, 27 Oct 2013)
New Revision: 23344
Trac: http://svn.gnucash.org/trac/changeset/23344
Added:
gnucash/trunk/src/doc/design/component-manager.texi
gnucash/trunk/src/doc/design/concept-index.texi
gnucash/trunk/src/doc/design/engine.texi
gnucash/trunk/src/doc/design/fdl.texi
gnucash/trunk/src/doc/design/function-index.texi
gnucash/trunk/src/doc/design/gnucash-design.texi
gnucash/trunk/src/doc/design/intro.texi
gnucash/trunk/src/doc/design/register.texi
gnucash/trunk/src/doc/design/reports.texi
gnucash/trunk/src/doc/design/top-level.texi
gnucash/trunk/src/doc/design/type-index.texi
gnucash/trunk/src/doc/design/user-preferences.texi
Removed:
gnucash/trunk/src/doc/design/component-manager.texinfo
gnucash/trunk/src/doc/design/concept-index.texinfo
gnucash/trunk/src/doc/design/engine.texinfo
gnucash/trunk/src/doc/design/fdl.texinfo
gnucash/trunk/src/doc/design/function-index.texinfo
gnucash/trunk/src/doc/design/gnucash-design.texinfo
gnucash/trunk/src/doc/design/intro.texinfo
gnucash/trunk/src/doc/design/register.texinfo
gnucash/trunk/src/doc/design/reports.texinfo
gnucash/trunk/src/doc/design/top-level.texinfo
gnucash/trunk/src/doc/design/type-index.texinfo
gnucash/trunk/src/doc/design/user-preferences.texinfo
Modified:
gnucash/trunk/src/doc/design/Makefile.am
Log:
Rename .texinfo files to .texi to get rid of the autogen.sh warning.
I am wondering if anybody still uses the content of this directory.
Modified: gnucash/trunk/src/doc/design/Makefile.am
===================================================================
--- gnucash/trunk/src/doc/design/Makefile.am 2013-10-27 21:57:42 UTC (rev 23343)
+++ gnucash/trunk/src/doc/design/Makefile.am 2013-10-28 01:02:53 UTC (rev 23344)
@@ -1,17 +1,17 @@
-info_TEXINFOS = gnucash-design.texinfo
+info_TEXINFOS = gnucash-design.texi
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
+ component-manager.texi \
+ concept-index.texi \
+ engine.texi \
+ fdl.texi \
+ function-index.texi \
+ intro.texi \
+ register.texi \
+ reports.texi \
+ top-level.texi \
+ type-index.texi \
+ user-preferences.texi
# These should included as part of the automake rule set. Perhaps I
# have a version skew between automake and texinfo.
Copied: gnucash/trunk/src/doc/design/component-manager.texi (from rev 23343, gnucash/trunk/src/doc/design/component-manager.texinfo)
===================================================================
--- gnucash/trunk/src/doc/design/component-manager.texi (rev 0)
+++ gnucash/trunk/src/doc/design/component-manager.texi 2013-10-28 01:02:53 UTC (rev 23344)
@@ -0,0 +1,396 @@
+ at node Component Manager
+ at chapter Component Manager
+ at cindex Component Manager
+
+ at strong{This whole document is completely outdated. Don't read this. All
+function names and every described structure has changed
+completely. Only read this if you want to know how gnucash looked like
+in 1999. This is completely outdated!}
+
+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.
+
+
+ at menu
+* Component Manager Introduction::
+* Refresh Mechanism::
+* CM Initialization and Shutdown::
+* Refresh Handlers::
+* Close Handlers::
+* Registering and Unregistering Components::
+* Watching Engine Objects::
+* Controlling Refreshes::
+* Finding Components::
+* Iterating over Components::
+ at end menu
+
+
+ at node Component Manager Introduction, Refresh Mechanism, Component Manager, Component Manager
+ at 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:
+
+
+ at itemize
+
+ at 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.
+
+ at 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.
+
+ at item Closing components.
+
+ at end itemize
+
+
+In particular, keeping components updated in the face of changes in the
+Engine is a difficult problem. Requirements for handling refreshes
+include:
+
+ at itemize
+
+ at 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.
+
+ at 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.
+
+ at 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.
+
+ at 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.
+
+ at item The Engine should not be managing GUI components.
+
+ at item The refresh mechanism should be extendable to a multi-user
+situation in which changes can come from external components.
+
+ at item Components should be able to specify which Engine entities
+can cause refreshes. This requirement allows the implementation
+to avoid unnecessary refreshing.
+
+ at end itemize
+
+
+ at node Refresh Mechanism, CM Initialization and Shutdown, Component Manager Introduction, Component Manager
+ at section Refresh Mechanism
+ at 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.
+
+ at example
+ ----------
+ | |
+ | Engine |
+ | |
+ ----------
+ /|\
+ |
+ |--- Events (from Engine)
+ |
+ \|/
+ -------------------------
+ | |
+ | Component Manager |
+ | |
+ -------------------------
+ / /|\ \ GUI Commands
+ / | \--- including refresh
+ / \|/ \ invocations (from CM)
+----------------- -----------------
+| | | |
+| GUI Component | | GUI Component | ...
+| | | |
+----------------- -----------------
+ at 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').
+
+
+ at node CM Initialization and Shutdown, Refresh Handlers, Refresh Mechanism, Component Manager
+ at section Initialization and Shutdown
+
+ at deftypefun void gnc_component_manager_init (void)
+Initialize the Component Manager. This should be called
+before using an other CM functions.
+ at end deftypefun
+
+ at deftypefun void gnc_component_manager_shutdown (void)
+Shutdown the Component Manager. This should be called
+to release Component Manager resources.
+ at end deftypefun
+
+
+ at node Refresh Handlers, Close Handlers, CM Initialization and Shutdown, Component Manager
+ at section Refresh Handlers
+ at tindex EventInfo
+
+When a component registers itself with the CM, it may specify two
+different handlers: a refresh handler and a close handler. A refresh
+handler is a function with the following type signature:
+
+ at deftp {Data type} GNCComponentRefreshHandler void (*) (GHashTable *@var{changes}, gpointer @var{user_data})
+This is the type signature of a refresh handler. The @var{changes} hash
+describes the Engine events which have occurred since the last refresh.
+It is used to determine whether a refresh is actually needed. It may,
+however, be @code{NULL}, meaning the component must perform a refresh.
+The @code{user_data} pointer is the data pointer supplied when the
+component was registered.
+ at end deftp
+
+When a refresh handler is invoked, it should perform the following actions:
+
+ at enumerate
+
+ at item Check if the component should be closed. When a refresh handler
+is invoked, any and all of the Engine objects which the component was
+referencing may have been destroyed, possibly making the component
+obsolete. For example, a dialog to edit the parameters of a specific
+Account should be automatically closed when the account is deleted. On
+the other hand, a list of all Accounts in a hierarchy should be updated
+when an Account is deleted, but not necessarily closed.
+
+Components must test for the destruction of critical Engine objects
+in two ways.
+
+ at enumerate
+
+ at item Use the @code{GUID} lookup functions (such as
+ at code{xaccAccountLookup}), to determine if the engine object is still
+bound to its @code{GUID}. Of course, this means that components should
+store the @code{GUID}s of critical Engine objects instead of simply
+storing their C pointers.
+
+ at item If the first test succeeds and the @var{changes} hash table
+of the refresh handler is non-NULL, the component should use the hash to
+determine of the GNC_EVENT_DESTROY event has ocurred for the Engine
+object in question. The @var{changes} hash is a mapping from
+ at code{GUID}s to @code{EventInfo} structures. An @code{EventInfo}
+structure has a single member, @code{event_mask}, of type
+ at code{GNCEngineEventType}. The @code{event_mask} is a logical or of the
+ at code{GNC_EVENT_CREATE}, @code{GNC_EVENT_MODIFY}, and
+ at code{GNC_EVENT_DESTROY} event types. Since refreshes may not occur with
+every Engine event, @code{event_mask} may have all three values.
+
+There is a utility function for accessing the @var{changes} hash:
+
+ at deftypefun {const EventInfo *} gnc_gui_get_entity_events (GHashTable * @var{changes}, const GUID * @var{entity})
+Return the event info for the entity specified by @var{entity}. If there
+are no events for that entity, @code{NULL} is returned.
+ at end deftypefun
+
+ at end enumerate
+
+If the @var{changes} hash is NULL, then the first test is sufficient
+to determine whether an object has been destroyed.
+
+If the refresh handler determines the component should be destroyed,
+it should destroy the component and return.
+
+ at item Check if the component should be refreshed. If the @var{changes}
+hash is @code{NULL}, then the component must refresh itself. Otherwise,
+it may use the @var{changes} hash to determine whether or not a refresh
+is actually necessary. However, since the component may specify which
+particular Engine objects are relevant (see "Watching Components"
+below), generally a component will simply refresh unconditionally.
+
+ at item Refresh the component if necessary. This includes updating the
+GUI as well as internal structures to reflect the new state of Engine
+objects.
+
+ at end enumerate
+
+
+ at node Close Handlers, Registering and Unregistering Components, Refresh Handlers, Component Manager
+ at section Close Handlers
+
+A close handler is a function with the following type signature:
+
+ at deftp {Data type} GNCComponentCloseHandler void (*) (gpointer @var{user_data})
+This is the type signature of a close handler. The @code{user_data}
+pointer is the data pointer supplied when the component was registered.
+ at end deftp
+
+The invocation of a close handler is a command to the component to close
+itself. The component must close itself -- the handler should not be
+ignored. The component is still responsible for unregistering itself
+with the Component Manager.
+
+
+ at node Registering and Unregistering Components, Watching Engine Objects, Close Handlers, Component Manager
+ at section Registering and Unregistering Components
+
+ at deftypefun gint gnc_register_gui_component (const char * @var{component_class}, GNCComponentRefreshHandler @var{refresh_handler}, GNCComponentCloseHandler @var{close_handler}, gpointer @var{user_data})
+Register a gui component with the Component Manager.
+
+The variable @var{component_class} is a string specifying a class of
+components. Certain CM functions can be performed on all components in a
+class. For that reason, components in the same class should all use the
+same type for @var{user_data}.
+
+ at var{refresh_handler} and @var{close_handler} specify the refresh and close
+handlers, respectively. Either or both may be @code{NULL}.
+
+The @var{user_data} is supplied as an argument when the handlers are invoked.
+
+The function returns the id of the newly-registered component, or
+ at code{NO_COMPONENT} if there was an error.
+ at end deftypefun
+
+After a refresh handler is registered, the component must use the API
+calls under "Watching Engine Objects" below to inform the Component
+Manager which engine entities are being watched, i.e., which engine
+entities may cause the component to need refreshing. When a component is
+first registered, it is not watching anything, and thus will not receive
+refresh events.
+
+ at deftypefun void gnc_unregister_gui_component (gint @var{component_id})
+Unregister the component with id @var{component} from the CM.
+ at end deftypefun
+
+ at deftypefun void gnc_unregister_gui_component_by_data (const char * @var{component_class}, gpointer @var{user_data})
+Unregister all gui components in the class @var{component_class} which have
+ at var{user_data} as a user data pointer.
+ at end deftypefun
+
+
+ at node Watching Engine Objects, Controlling Refreshes, Registering and Unregistering Components, Component Manager
+ at section Watching Engine Objects
+
+ at deftypefun void gnc_gui_component_watch_entity (gint @var{component_id}, const GUID * @var{entity}, GNCEngineEventType @var{event_mask})
+If @var{event_mask} is non-zero, add the Engine entity specified by
+ at var{entity} to the list of entities being watched by the component with
+id @var{component_id}. Only the events specified by @var{events} are
+watched. If @var{event_mask} is 0, the call turns off watching for the
+entity.
+ at end deftypefun
+
+ at deftypefun void gnc_gui_component_watch_entity_type (gint @var{component_id}, GNCIdType @var{entity_type}, GNCEngineEventType @var{event_mask})
+if @var{event_mask}, turn on watching for all entities of @var{entity_type}.
+Only events specified by @var{event_mask} are watched. If @var{event_mask}
+is 0, turns off watching for the entity type.
+ at end deftypefun
+
+ at deftypefun void gnc_gui_component_clear_watches (gint @var{component_id})
+Clear all watches for the component with id @var{component_id}.
+ at end deftypefun
+
+
+ at node Controlling Refreshes, Finding Components, Watching Engine Objects, Component Manager
+ at section Controlling Refreshes
+
+ at deftypefun void gnc_suspend_gui_refresh (void)
+Suspend the invocation of refresh handlers by the Component Manager.
+This routine may be called multiple times. Each call increases the
+suspend counter which starts at zero. When refreshes are not suspended,
+any engine event causes a refresh cycle in which the refresh handler for
+every component watching for that event is invoked.
+ at end deftypefun
+
+ at deftypefun void gnc_resume_gui_refresh (void)
+Resume the invocation of refresh handlers by the Component Manager.
+Each call reduces the suspend counter by one. When the counter reaches
+zero, all events which have occured since the last refresh are collected
+and passed to refresh handlers via the @var{changes} argument. Refresh
+handlers will still be excluded based on their watches.
+ at end deftypefun
+
+ at deftypefun void gnc_gui_refresh_all (void)
+Force all components to refresh, i.e., invoke all refresh handlers
+with a @code{NULL} value for @var{changes}.
+
+This routine may only be invoked when the suspend counter is zero. It
+should never be mixed with the suspend/resume refresh routines.
+ at end deftypefun
+
+ at deftypefun gboolean gnc_gui_refresh_suspended (void)
+Returns TRUE if GUI refreshing is currently suspended.
+ at end deftypefun
+
+
+ at node Finding Components, Iterating over Components, Controlling Refreshes, Component Manager
+ at section Finding Components
+
+The Component Manager API provides two functions that allow components
+to be searched for. Each function uses a find handler to perform the
+actual search work. A find handler is a function with the following
+signature:
+
+ at deftp {Data type} GNCComponentFindHandler gboolean (*) (gpointer @var{find_data}, gpointer @var{user_data})
+A find handler is invoked with the @var{find_data} specified in the search
+API call, and the @var{user_data} of a particular component. The handler
+should return TRUE if the component matches the search criteria and FALSE
+otherwise.
+ at end deftp
+
+ at deftypefun {GList *} gnc_find_gui_components (const char * @var{component_class}, GNCComponentFindHandler @var{find_handler}, gpointer @var{find_data})
+Search for all components in class @var{component_class} using @var{find_handler}. Return a @code{GList} of the user data pointers of matching components.
+ at end deftypefun
+
+ at deftypefun gpointer gnc_find_first_gui_component (const char * @var{component_class}, GNCComponentFindHandler @var{find_handler}, gpointer @var{find_data})
+Like @code{gnc_find_gui_components} above, but return the user data pointer
+of the first matching component, or @code{NULL} if there are no matching
+components.
+ at end deftypefun
+
+
+ at node Iterating over Components, , Finding Components, Component Manager
+ at section Iterating over Components
+
+The Component Manager API provides a function for iterating over all
+components in a class as well as all registered components regardless
+of class.
+
+In either case, a generic component handler is invoked for each
+component. The handler has the following signature:
+
+ at deftp {Data type} GNCComponentHandler void (*) (const char * @var{class}, gint @var{component_id}, gpointer @var{iter_data})
+The component handler is invoked with the @var{class},
+ at var{component_id} of a particular component, as well as the
+ at var{iter_data} supplied in the iteration API call.
+ at end deftp
+
+ at deftypefun void gnc_forall_gui_components (const char * @var{component_class}, GNCComponentHandler @var{handler}, gpointer @var{iter_data})
+Apply @var{handler} to every component in @var{component_class}. If
+ at var{component_class} is @code{NULL}, then iteration is performed over
+every registered component. @var{iter_data} is supplied to @var{handler}
+as the third argument.
+ at end deftypefun
Deleted: gnucash/trunk/src/doc/design/component-manager.texinfo
===================================================================
--- gnucash/trunk/src/doc/design/component-manager.texinfo 2013-10-27 21:57:42 UTC (rev 23343)
+++ gnucash/trunk/src/doc/design/component-manager.texinfo 2013-10-28 01:02:53 UTC (rev 23344)
@@ -1,396 +0,0 @@
- at node Component Manager
- at chapter Component Manager
- at cindex Component Manager
-
- at strong{This whole document is completely outdated. Don't read this. All
-function names and every described structure has changed
-completely. Only read this if you want to know how gnucash looked like
-in 1999. This is completely outdated!}
-
-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.
-
-
- at menu
-* Component Manager Introduction::
-* Refresh Mechanism::
-* CM Initialization and Shutdown::
-* Refresh Handlers::
-* Close Handlers::
-* Registering and Unregistering Components::
-* Watching Engine Objects::
-* Controlling Refreshes::
-* Finding Components::
-* Iterating over Components::
- at end menu
-
-
- at node Component Manager Introduction, Refresh Mechanism, Component Manager, Component Manager
- at 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:
-
-
- at itemize
-
- at 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.
-
- at 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.
-
- at item Closing components.
-
- at end itemize
-
-
-In particular, keeping components updated in the face of changes in the
-Engine is a difficult problem. Requirements for handling refreshes
-include:
-
- at itemize
-
- at 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.
-
- at 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.
-
- at 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.
-
- at 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.
-
- at item The Engine should not be managing GUI components.
-
- at item The refresh mechanism should be extendable to a multi-user
-situation in which changes can come from external components.
-
- at item Components should be able to specify which Engine entities
-can cause refreshes. This requirement allows the implementation
-to avoid unnecessary refreshing.
-
- at end itemize
-
-
- at node Refresh Mechanism, CM Initialization and Shutdown, Component Manager Introduction, Component Manager
- at section Refresh Mechanism
- at 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.
-
- at example
- ----------
- | |
- | Engine |
- | |
- ----------
- /|\
- |
- |--- Events (from Engine)
- |
- \|/
- -------------------------
- | |
- | Component Manager |
- | |
- -------------------------
- / /|\ \ GUI Commands
- / | \--- including refresh
- / \|/ \ invocations (from CM)
------------------ -----------------
-| | | |
-| GUI Component | | GUI Component | ...
-| | | |
------------------ -----------------
- at 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').
-
-
- at node CM Initialization and Shutdown, Refresh Handlers, Refresh Mechanism, Component Manager
- at section Initialization and Shutdown
-
- at deftypefun void gnc_component_manager_init (void)
-Initialize the Component Manager. This should be called
-before using an other CM functions.
- at end deftypefun
-
- at deftypefun void gnc_component_manager_shutdown (void)
-Shutdown the Component Manager. This should be called
-to release Component Manager resources.
- at end deftypefun
-
-
- at node Refresh Handlers, Close Handlers, CM Initialization and Shutdown, Component Manager
- at section Refresh Handlers
- at tindex EventInfo
-
-When a component registers itself with the CM, it may specify two
-different handlers: a refresh handler and a close handler. A refresh
-handler is a function with the following type signature:
-
- at deftp {Data type} GNCComponentRefreshHandler void (*) (GHashTable *@var{changes}, gpointer @var{user_data})
-This is the type signature of a refresh handler. The @var{changes} hash
-describes the Engine events which have occurred since the last refresh.
-It is used to determine whether a refresh is actually needed. It may,
-however, be @code{NULL}, meaning the component must perform a refresh.
-The @code{user_data} pointer is the data pointer supplied when the
-component was registered.
- at end deftp
-
-When a refresh handler is invoked, it should perform the following actions:
-
- at enumerate
-
- at item Check if the component should be closed. When a refresh handler
-is invoked, any and all of the Engine objects which the component was
-referencing may have been destroyed, possibly making the component
-obsolete. For example, a dialog to edit the parameters of a specific
-Account should be automatically closed when the account is deleted. On
-the other hand, a list of all Accounts in a hierarchy should be updated
-when an Account is deleted, but not necessarily closed.
-
-Components must test for the destruction of critical Engine objects
-in two ways.
-
- at enumerate
-
- at item Use the @code{GUID} lookup functions (such as
- at code{xaccAccountLookup}), to determine if the engine object is still
-bound to its @code{GUID}. Of course, this means that components should
-store the @code{GUID}s of critical Engine objects instead of simply
-storing their C pointers.
-
- at item If the first test succeeds and the @var{changes} hash table
-of the refresh handler is non-NULL, the component should use the hash to
-determine of the GNC_EVENT_DESTROY event has ocurred for the Engine
-object in question. The @var{changes} hash is a mapping from
- at code{GUID}s to @code{EventInfo} structures. An @code{EventInfo}
-structure has a single member, @code{event_mask}, of type
- at code{GNCEngineEventType}. The @code{event_mask} is a logical or of the
- at code{GNC_EVENT_CREATE}, @code{GNC_EVENT_MODIFY}, and
- at code{GNC_EVENT_DESTROY} event types. Since refreshes may not occur with
-every Engine event, @code{event_mask} may have all three values.
-
-There is a utility function for accessing the @var{changes} hash:
-
- at deftypefun {const EventInfo *} gnc_gui_get_entity_events (GHashTable * @var{changes}, const GUID * @var{entity})
-Return the event info for the entity specified by @var{entity}. If there
-are no events for that entity, @code{NULL} is returned.
- at end deftypefun
-
- at end enumerate
-
-If the @var{changes} hash is NULL, then the first test is sufficient
-to determine whether an object has been destroyed.
-
-If the refresh handler determines the component should be destroyed,
-it should destroy the component and return.
-
- at item Check if the component should be refreshed. If the @var{changes}
-hash is @code{NULL}, then the component must refresh itself. Otherwise,
-it may use the @var{changes} hash to determine whether or not a refresh
-is actually necessary. However, since the component may specify which
-particular Engine objects are relevant (see "Watching Components"
-below), generally a component will simply refresh unconditionally.
-
- at item Refresh the component if necessary. This includes updating the
-GUI as well as internal structures to reflect the new state of Engine
-objects.
-
- at end enumerate
-
-
- at node Close Handlers, Registering and Unregistering Components, Refresh Handlers, Component Manager
- at section Close Handlers
-
-A close handler is a function with the following type signature:
-
- at deftp {Data type} GNCComponentCloseHandler void (*) (gpointer @var{user_data})
-This is the type signature of a close handler. The @code{user_data}
-pointer is the data pointer supplied when the component was registered.
- at end deftp
-
-The invocation of a close handler is a command to the component to close
-itself. The component must close itself -- the handler should not be
-ignored. The component is still responsible for unregistering itself
-with the Component Manager.
-
-
- at node Registering and Unregistering Components, Watching Engine Objects, Close Handlers, Component Manager
- at section Registering and Unregistering Components
-
- at deftypefun gint gnc_register_gui_component (const char * @var{component_class}, GNCComponentRefreshHandler @var{refresh_handler}, GNCComponentCloseHandler @var{close_handler}, gpointer @var{user_data})
-Register a gui component with the Component Manager.
-
-The variable @var{component_class} is a string specifying a class of
-components. Certain CM functions can be performed on all components in a
-class. For that reason, components in the same class should all use the
-same type for @var{user_data}.
-
- at var{refresh_handler} and @var{close_handler} specify the refresh and close
-handlers, respectively. Either or both may be @code{NULL}.
-
-The @var{user_data} is supplied as an argument when the handlers are invoked.
-
-The function returns the id of the newly-registered component, or
- at code{NO_COMPONENT} if there was an error.
- at end deftypefun
-
-After a refresh handler is registered, the component must use the API
-calls under "Watching Engine Objects" below to inform the Component
-Manager which engine entities are being watched, i.e., which engine
-entities may cause the component to need refreshing. When a component is
-first registered, it is not watching anything, and thus will not receive
-refresh events.
-
- at deftypefun void gnc_unregister_gui_component (gint @var{component_id})
-Unregister the component with id @var{component} from the CM.
- at end deftypefun
-
- at deftypefun void gnc_unregister_gui_component_by_data (const char * @var{component_class}, gpointer @var{user_data})
-Unregister all gui components in the class @var{component_class} which have
- at var{user_data} as a user data pointer.
- at end deftypefun
-
-
- at node Watching Engine Objects, Controlling Refreshes, Registering and Unregistering Components, Component Manager
- at section Watching Engine Objects
-
- at deftypefun void gnc_gui_component_watch_entity (gint @var{component_id}, const GUID * @var{entity}, GNCEngineEventType @var{event_mask})
-If @var{event_mask} is non-zero, add the Engine entity specified by
- at var{entity} to the list of entities being watched by the component with
-id @var{component_id}. Only the events specified by @var{events} are
-watched. If @var{event_mask} is 0, the call turns off watching for the
-entity.
- at end deftypefun
-
- at deftypefun void gnc_gui_component_watch_entity_type (gint @var{component_id}, GNCIdType @var{entity_type}, GNCEngineEventType @var{event_mask})
-if @var{event_mask}, turn on watching for all entities of @var{entity_type}.
-Only events specified by @var{event_mask} are watched. If @var{event_mask}
-is 0, turns off watching for the entity type.
- at end deftypefun
-
- at deftypefun void gnc_gui_component_clear_watches (gint @var{component_id})
-Clear all watches for the component with id @var{component_id}.
- at end deftypefun
-
-
- at node Controlling Refreshes, Finding Components, Watching Engine Objects, Component Manager
- at section Controlling Refreshes
-
- at deftypefun void gnc_suspend_gui_refresh (void)
-Suspend the invocation of refresh handlers by the Component Manager.
-This routine may be called multiple times. Each call increases the
-suspend counter which starts at zero. When refreshes are not suspended,
-any engine event causes a refresh cycle in which the refresh handler for
-every component watching for that event is invoked.
- at end deftypefun
-
- at deftypefun void gnc_resume_gui_refresh (void)
-Resume the invocation of refresh handlers by the Component Manager.
-Each call reduces the suspend counter by one. When the counter reaches
-zero, all events which have occured since the last refresh are collected
-and passed to refresh handlers via the @var{changes} argument. Refresh
-handlers will still be excluded based on their watches.
- at end deftypefun
-
- at deftypefun void gnc_gui_refresh_all (void)
-Force all components to refresh, i.e., invoke all refresh handlers
-with a @code{NULL} value for @var{changes}.
-
-This routine may only be invoked when the suspend counter is zero. It
-should never be mixed with the suspend/resume refresh routines.
- at end deftypefun
-
- at deftypefun gboolean gnc_gui_refresh_suspended (void)
-Returns TRUE if GUI refreshing is currently suspended.
- at end deftypefun
-
-
- at node Finding Components, Iterating over Components, Controlling Refreshes, Component Manager
- at section Finding Components
-
-The Component Manager API provides two functions that allow components
-to be searched for. Each function uses a find handler to perform the
-actual search work. A find handler is a function with the following
-signature:
-
- at deftp {Data type} GNCComponentFindHandler gboolean (*) (gpointer @var{find_data}, gpointer @var{user_data})
-A find handler is invoked with the @var{find_data} specified in the search
-API call, and the @var{user_data} of a particular component. The handler
-should return TRUE if the component matches the search criteria and FALSE
-otherwise.
- at end deftp
-
- at deftypefun {GList *} gnc_find_gui_components (const char * @var{component_class}, GNCComponentFindHandler @var{find_handler}, gpointer @var{find_data})
-Search for all components in class @var{component_class} using @var{find_handler}. Return a @code{GList} of the user data pointers of matching components.
- at end deftypefun
-
- at deftypefun gpointer gnc_find_first_gui_component (const char * @var{component_class}, GNCComponentFindHandler @var{find_handler}, gpointer @var{find_data})
-Like @code{gnc_find_gui_components} above, but return the user data pointer
-of the first matching component, or @code{NULL} if there are no matching
-components.
- at end deftypefun
-
-
- at node Iterating over Components, , Finding Components, Component Manager
- at section Iterating over Components
-
-The Component Manager API provides a function for iterating over all
-components in a class as well as all registered components regardless
-of class.
-
-In either case, a generic component handler is invoked for each
-component. The handler has the following signature:
-
- at deftp {Data type} GNCComponentHandler void (*) (const char * @var{class}, gint @var{component_id}, gpointer @var{iter_data})
-The component handler is invoked with the @var{class},
- at var{component_id} of a particular component, as well as the
- at var{iter_data} supplied in the iteration API call.
- at end deftp
-
- at deftypefun void gnc_forall_gui_components (const char * @var{component_class}, GNCComponentHandler @var{handler}, gpointer @var{iter_data})
-Apply @var{handler} to every component in @var{component_class}. If
- at var{component_class} is @code{NULL}, then iteration is performed over
-every registered component. @var{iter_data} is supplied to @var{handler}
-as the third argument.
- at end deftypefun
Copied: gnucash/trunk/src/doc/design/concept-index.texi (from rev 23343, gnucash/trunk/src/doc/design/concept-index.texinfo)
===================================================================
--- gnucash/trunk/src/doc/design/concept-index.texi (rev 0)
+++ gnucash/trunk/src/doc/design/concept-index.texi 2013-10-28 01:02:53 UTC (rev 23344)
@@ -0,0 +1,4 @@
+ at node Concept Index, , Data Type Index, Top
+ at unnumbered Concept Index
+
+ at printindex cp
Deleted: gnucash/trunk/src/doc/design/concept-index.texinfo
===================================================================
--- gnucash/trunk/src/doc/design/concept-index.texinfo 2013-10-27 21:57:42 UTC (rev 23343)
+++ gnucash/trunk/src/doc/design/concept-index.texinfo 2013-10-28 01:02:53 UTC (rev 23344)
@@ -1,4 +0,0 @@
- at node Concept Index, , Data Type Index, Top
- at unnumbered Concept Index
-
- at printindex cp
Copied: gnucash/trunk/src/doc/design/engine.texi (from rev 23343, gnucash/trunk/src/doc/design/engine.texinfo)
===================================================================
--- gnucash/trunk/src/doc/design/engine.texi (rev 0)
+++ gnucash/trunk/src/doc/design/engine.texi 2013-10-28 01:02:53 UTC (rev 23344)
@@ -0,0 +1,2842 @@
+ at node Engine, Component Manager, Top Level, Top
+ at chapter Engine
+ at cindex The Engine
+
+ at strong{This whole document is completely outdated. Don't read this. All
+function names and every described structure has changed
+completely. Only read this if you want to know how gnucash looked like
+in 1999. This is completely outdated!}
+
+The Engine provides an interface to a financial engine with three basic
+financial entities: Accounts, Transactions (known as Journal Entries in
+accounting practice), and Splits (known as Ledger Entries). These three
+entities are the central data structures of the GnuCash financial data
+model.
+
+In addition, the Engine provides the abstraction of Account Groups
+(collections of related accounts) and GNCBooks. A GNCBook abstracts both
+a set of related GnuCash data (financial entities plus additional
+information such as budgets, per-file preferences, etc.) plus a
+file-editing session allowing transparent support for locking and
+implementation with other backends such as SQL.
+
+The Engine code contains no GUI code whatsoever and is designed to
+be created as a shared library for use by other programs.
+
+ at menu
+* Engine Introduction::
+* Using and Extending the Engine API::
+* Globally Unique Identifiers::
+* Numeric Library::
+* Key-Value Pair Frames::
+* Events::
+* Commodities::
+* Commodity Tables::
+* Prices::
+* Price Databases::
+* Splits::
+* Transactions::
+* Accounts::
+* Account Groups::
+* GNCBooks::
+* Scrub::
+ at end menu
+
+
+ at node Engine Introduction, Using and Extending the Engine API, Engine, Engine
+ at section Introduction
+
+Splits (@pxref{Splits}), or "Ledger Entries" are the fundamental
+accounting units. Each Split consists of an amount (number of dollar
+bills, number of shares, etc.), the value of that amount expressed in
+a (possibly) different currency than the amount, a Memo, a pointer to
+the parent Transaction, a pointer to the debited Account, a reconciled
+flag and timestamp, an "Action" field, and a key-value frame which can
+store arbitrary data (@pxref{Key-Value Pair Frames}).
+
+Transactions (@pxref{Transactions}) embody the notion of "double entry"
+accounting. A Transaction consists of a date, a description, an ID number, a
+list of one or more Splits, and a key-value frame. The transaction
+also specifies the currency with which all of the splits will be
+valued. When double-entry rules are enforced, the total value of
+the splits are zero. If there are only two splits,
+then the value of one must be positive, the other negative: this denotes
+that one account is debited, and another is credited by an equal
+amount. By forcing the value of the splits to always 'add up' to
+zero, we can gaurentee that the balances of the accounts are always
+correctly balanced.
+
+The engine does not enforce double-entry accounting, but provides an API
+to enable user-code to find unbalanced transactions and 'repair' them so
+that they are in balance. @xref{Scrub}.
+
+Note the sum of the values of Splits in a Transaction is always computed
+with respect to a currency; thus splits can be balanced even when they
+are in different currencies, as long as they share a common currency.
+This feature allows currency-trading accounts to be established.
+
+Every Split must point to its parent Transaction, and that Transaction
+must in turn include that Split in the Transaction's list of Splits. A
+Split can belong to at most one Transaction. These relationships are
+enforced by the engine. The engine user cannnot accidentally destroy
+this relationship as long as they stick to using the API and never
+access internal structures directly.
+
+Splits are grouped into Accounts (@pxref{Accounts}) which are also known
+as "Ledgers" in accounting practice. Each Account consists of a list of
+Splits that debit that Account. To ensure consistency, if a Split points
+to an Account, then the Account must point to the Split, and vice-versa.
+A Split can belong to at most one Account. Besides merely containing a
+list of Splits, the Account structure also give the Account a name, a
+code number, description and notes fields, a key-value frame, a pointer
+to the commodity that is used for all splits in this account. The
+commodity can be the name of anything traded and tradable: a stock
+(e.g. "IBM", "McDonald's"), a currency (e.g. "USD", "GBP"), or
+anything added to the commodity table.
+
+Accounts can be arranged in a hierarchical tree. The nodes of the tree
+are called "Account Groups" (@pxref{Account Groups}). By accounting
+convention, the value of an Account is equal to the value of all of its
+Splits plus the value of all of its sub-Accounts.
+
+
+ at node Using and Extending the Engine API, Globally Unique Identifiers, Engine Introduction, Engine
+ at section Using and Extending the Engine API
+
+Engine API calls are named using a specific convention. For example,
+the function to access the Memo field of a Split is
+ at code{xaccSplitGetMemo}. The prefix @code{xacc} comes
+first at footnote{The @code{xacc} prefix is a historical artifact. GnuCash
+was derived from X-Accountant by Robin Clark.}, followed by the name of
+the entity for which the API call applies (@code{Split}), followed by
+the action performed by the call (@code{Get}), followed by the name of
+the field being accessed (@code{Memo}). Future API calls should conform
+to this naming convention.
+
+The formal arguments to Engine API calls always begin with the entity to
+which the call applies. Thus, the arguments to @code{xaccSplitSetMemo}
+are the @code{Split} pointer followed by the pointer to a memo
+string. Future API calls should also conform to this convention.
+
+Engine API calls should be implemented to behave as gracefully as
+possible with unexpected input. Specifically, public API calls should
+gracefully handle @code{NULL} pointer arguments. User code should be
+able to handle @code{NULL} return values from Engine calls as well.
+
+
+ at node Globally Unique Identifiers, Numeric Library, Using and Extending the Engine API, Engine
+ at section Globally Unique Identifiers
+ at cindex Globally Unique Identifier
+ at tindex GUID
+
+It is common for Engine structures to reference other Engine structures.
+For example, an Account must reference its Splits, its parent Account
+Group, and its child Account Group. Furthermore, other GnuCash modules
+may need to reference Engine structures. For example, a GUI
+implementation may wish to save a list of Accounts which the user has
+open when the application exits in order to restore that same state upon
+the next invocation.
+
+One way to uniquely identify an Engine structure, at least while the
+program is running, is using the C pointer which points to the
+structure. C pointers have the advantage of speed, but also have some
+disadvantages:
+
+ at itemize
+
+ at item
+Pointers cannot be used in data files and are not persistant across
+different program invocations.
+
+ at item
+When an entity is destroyed, every other structure which references that
+entity through a direct pointer must be immediately updated to prevent
+illegal accesses.
+
+ at end itemize
+
+The @dfn{GUID} (Globally Unique Identifier) provides a way to reference
+Engine structures that is more flexible than C pointers. Each Engine
+structure has an associated GUID which can be used to reference that
+structure. Engine GUIDs have the following features:
+
+ at itemize
+
+ at item
+The GUID is permanent, i.e., it persists between invocations of GnuCash.
+
+ at item
+The GUID is guaranteed to be unique with the set of all Splits,
+Transactions, and Accounts in the hierarchy of which the structure
+is a member.
+
+ at item
+With very high probability, the GUID is unique among all GUIDs
+created by any invocation of GnuCash, all over the world.
+
+ at item
+GUIDs can be efficiently encoded in a string representation.
+
+ at end itemize
+
+
+ at menu
+* When to use GUIDs::
+* GUID Types::
+* How to use GUIDs::
+* GUIDs and GnuCash Entities::
+* The GUID Generator::
+ at end menu
+
+ at node When to use GUIDs, GUID Types, Globally Unique Identifiers, Globally Unique Identifiers
+ at subsection When to use GUIDs
+ at cindex When to use GUIDs
+
+Although GUIDs are very flexible, the engine structures like Accounts
+will probably continue to use C pointers for the forseeable future,
+since they are much faster (and in certain respects more convenient)
+than using GUIDs. In general, however, it is much safer to use GUIDs.
+In particular, you should consider using GUIDs if any of the following
+is true:
+
+ at itemize
+
+ at item
+You need to save a reference to an engine structure in a file.
+
+ at item
+You need to save a reference to an engine structure that could
+be deleted in between accesses to the saved reference.
+
+ at end itemize
+
+
+ at node GUID Types, How to use GUIDs, When to use GUIDs, Globally Unique Identifiers
+ at subsection GUID Types
+ at tindex GNCIdType
+
+The GUIDs in GnuCash are typed using the enum @code{GNCIdType}.
+Possible values and their meanings for GUID types are:
+
+ at table @code
+
+ at item GNC_ID_NONE
+The GUID does not currently refer to a GnuCash entity, though it
+could refer to one in the future.
+
+ at item GNC_ID_NULL
+The GUID does not, and never will, refer to a GnuCash entity.
+
+ at item GNC_ID_ACCOUNT
+The GUID refers to an Account (@pxref{Accounts}).
+
+ at item GNC_ID_TRANS
+The GUID refers to a Transation (@pxref{Transactions}).
+
+ at item GNC_ID_SPLIT
+The GUID refers to a Split (@pxref{Splits}).
+
+ at end table
+
+ at deftypefun GNCIdType xaccGUIDType (const GUID * @var{guid})
+Return the type associated with @var{guid}.
+ at end deftypefun
+
+ at deftypefun {const GUID *} xaccGUIDNull (void)
+Return a GUID which is guaranteed to always have type @code{GNC_ID_NULL}.
+ at end deftypefun
+
+
+ at node How to use GUIDs, GUIDs and GnuCash Entities, GUID Types, Globally Unique Identifiers
+ at subsection How to use GUIDs
+
+The Engine API functions which access the GUID for a specific entity
+return a pointer to the GUID. NOTE: Do not store the pointer
+itself! Instead, store a copy of the GUID. Storing the pointer itself
+would present some of the same problems as using the account pointer
+directly. Example:
+
+ at example
+@{
+ GUID saved_guid;
+ Account *account;
+
+ account = < something to get an Account pointer >
+
+ saved_guid = *xaccAccountGetGUID(account);
+
+ ...
+
+ account = xaccAccountLookup(&saved_guid);
+
+ ...
+@}
+ at end example
+
+You can compare two GUIDs with the following functions.
+
+ at deftypefun gboolean guid_equal (const GUID * @var{guid_1}, const GUID * @var{guid_2})
+Compare two guids and return TRUE if they are both non-NULL and equal.
+ at end deftypefun
+
+ at deftypefun gint guid_compare (const GUID * @var{g1}, const GUID * @var{g2})
+Return the @code{memcmp} of the two GUID's.
+ at end deftypefun
+
+
+You can encode and decode GUIDs and their string representations using the
+next two functions.
+
+ at deftypefun {const char *} guid_to_string (const GUID * @var{guid})
+Return a null-terminated string encoding of @var{guid}. String encodings
+of identifiers are hex numbers printed only with the characters @code{0}
+through @code{9} and @code{a} through @code{f}. The encoding will
+always be @code{GUID_ENCODING_LENGTH} characters long. The returned
+string must NOT be freed when no longer needed.
+ at end deftypefun
+
+ at deftypefun {char *} guid_to_string_buff (const GUID * @var{guid}, char * @var{buff})
+This routine does the same work as @code{guid_to_string}, except that the
+string is written into the memory pointed at by @var{buff}. The
+buffer must be at least GUID_ENCODING_LENGTH+1 characters long.
+This routine is handy for avoiding a malloc/free cycle.
+It returns a pointer to the @emph{end} of what was written.
+(i.e. it can be used like @code{stpcpy} during string concatenation)
+ at end deftypefun
+
+ at deftypefun gboolean string_to_guid (const char * @var{string}, GUID * @var{guid})
+Given a string, decode an id into @var{guid} if @var{guid} is
+non-NULL. The function returns TRUE if the string was a valid 32
+character hexadecimal number. This function accepts both upper and lower
+case hex digits. If the return value is FALSE, the effect on @var{guid}
+is undefined.
+ at end deftypefun
+
+
+You can allocate and deallocate space for GUIDs using standard
+memory routines. However, if your code is allocating and deallocating
+lots of GUID objects, then the next two functions should be used.
+
+ at deftypefun {GUID *} xaccGUIDMalloc (void)
+Return newly allocated memory for a GUID object. The memory must
+be freed with @code{xaccGUIDFree}. In general, this function is
+faster than using the standard libc allocators.
+ at end deftypefun
+
+ at deftypefun void xaccGUIDFree (GUID * @var{guid})
+Free the space for a GUID that was allocated with @code{xaccGUIDMalloc}.
+ at end deftypefun
+
+
+You can use the following two functions to aid in using GUIDS in hash
+tables.
+
+ at deftypefun guint guid_hash_to_guint (gconstpointer @var{ptr})
+Return a hash value suitable for use with a @code{GHashTable}.
+ at var{ptr} must point to a GUID.
+ at end deftypefun
+
+ at deftypefun {GHashTable *} guid_hash_table_new (void)
+Return a new @code{GHashTable} which uses GUIDs as keys.
+ at end deftypefun
+
+
+ at node GUIDs and GnuCash Entities, The GUID Generator, How to use GUIDs, Globally Unique Identifiers
+ at subsection GUIDs and GnuCash Entities
+
+This section documents a low-level API for associating entities with
+GUIDs. User code and general engine code should not use this API;
+instead use the API documented in the sections for the specific GnuCash
+entities such as Accounts and Transactions.
+
+ at deftypefun void xaccGUIDNew (GUID * @var{guid})
+Generate a new guid. This function is guaranteed to return a guid that
+is unique within the scope of all GnuCash entities being managed by the
+the current invocation of GnuCash. GnuCash routines should always use
+this function and not @code{guid_new}!
+ at end deftypefun
+
+ at deftypefun {void *} xaccLookupEntity (const GUID * @var{guid}, GNCIdType @var{entity_type})
+Lookup an entity given an id and a type. If there is no entity
+associated with the id, or if it has a different type, NULL is returned.
+ at end deftypefun
+
+ at deftypefun void xaccStoreEntity (void * @var{entity}, const GUID * @var{guid}, GNCIdType entity_type)
+Store the given entity under the given id with the given type.
+ at end deftypefun
+
+ at deftypefun void xaccRemoveEntity (const GUID * @var{guid})
+Remove any existing association between an entity and the given id. The
+entity is not changed in any way.
+ at end deftypefun
+
+
+ at node The GUID Generator, , GUIDs and GnuCash Entities, Globally Unique Identifiers
+ at subsection The GUID Generator
+ at cindex The GUID Generator
+
+GUIDs are created by the GUID generator. The API for this generator is
+low-level and should not be used by user-code.
+
+ at deftypefun void guid_init (void)
+Initialize the GUID generator with a variety of random sources including
+common system files and /dev/random.
+ at end deftypefun
+
+ at deftypefun void guid_init_with_salt (const void * @var{salt}, size_t @var{salt_len})
+Initialize the GUID generator with guid_init() and with the given
+sequence of arbitrary binary data.
+ at end deftypefun
+
+ at deftypefun void guid_init_only_salt (const void * @var{salt}, size_t @var{salt_len})
+Initialize the GUID generator using only the given sequence of arbitrary
+binary data. This provides a way to reliably obtain a given sequence of
+GUIDs.
+ at end deftypefun
+
+ at deftypefun void guid_new (GUID * @var{guid})
+Create a new GUID and store it in @var{guid}. This is a low-level function!
+GnuCash code should use @code{xaccGUIDNew}.
+ at end deftypefun
+
+
+ at node Numeric Library, Key-Value Pair Frames, Globally Unique Identifiers, Engine
+ at section Numeric Library
+ at cindex Numeric Library
+ at tindex gnc_numeric
+
+=============== The documentation below for gnc_numeric is obsolete
+ and has been superseeded by the gnc_numeric docs in the header file.
+=========================================
+
+Financial quantities in GnuCash (Split quantities and values) are stored
+as exact quantities measured in the smallest denominational unit of the
+appropriate currency. For example, 100.50 US Dollars would be stored as
+(10050 / 100) US Dollars. GnuCash uses the @code{gnc_numeric} datatype
+to store financial quantities.
+
+The @code{gnc_numeric} API provides data types and functions for
+manipulating exact numeric quantities. While the @code{gnc_numeric}
+library was developed to represent and operate on exact financial
+quantities in GnuCash, the library is also (hopefully) suitable for use
+in any application where exact numeric representation for rational
+numbers is needed.
+
+A @code{gnc_numeric} value represents a number in rational form, with a
+64-bit @code{long long} integer as numerator and denominator. If more
+precision, a higher-precision representation of irrational numbers, or a
+wider dynamic range is needed, a floating point format may be
+appropriate. There are reasonable rational approximations to common
+irrational constants (@pxref{Numeric Example}), but the transcendental
+functions have not been implemented for @code{gnc_numeric} objects.
+
+ at menu
+* Standard Numeric Arguments::
+* Creating Numeric Objects::
+* Basic Arithmetic Operations::
+* Numeric Comparisons and Predicates::
+* Numeric Denominator Conversion::
+* Numeric Floating Point Conversion::
+* Numeric String Conversion::
+* Numeric Error Handling ::
+* Numeric Example::
+ at end menu
+
+ at node Standard Numeric Arguments, Creating Numeric Objects, Numeric Library, Numeric Library
+ at subsection Standard Numeric Arguments
+ at cindex Standard Numeric Arguments
+
+=============== The documentation below for gnc_numeric is obsolete
+ and has been superseeded by the gnc_numeric docs in the header file.
+=========================================
+
+It is useful to specify a denominator in cases where it is known that
+the output value is of constrained precision. For example, monetary
+transactions must be executed in an integer number of the "smallest
+currency unit" of the transaction. In US Dollars, the smallest currency
+unit is the cent, and all monetary transactions must be done in units of
+cents. Therefore, any fractional cents in a computed price must be
+rounded away.
+
+Most of the @code{gnc_numeric} arithmetic functions take two arguments
+in addition to their numeric args: @var{denom}, which is the denominator
+to use in the output @code{gnc_numeric object}, and @var{how}, which
+describes how the arithmetic result is to be converted to that
+denominator. This combination of output denominator and rounding policy
+allows the results of financial and other exact computations to be
+properly rounded to the appropriate units.
+
+Valid values for @var{denom} are:
+
+ at table @code
+
+ at item n (positive int)
+Use the number @code{n} as the denominator of the output value.
+
+ at item GNC_DENOM_RECIPROCAL (n)
+Use the value @code{1/n} as the denominator of the output value.
+
+ at item GNC_DENOM_AUTO
+Compute an appropriate denominator automatically. Flags in the @var{how}
+argument will specify how to compute the denominator.
+
+ at end table
+
+
+Valid values for @var{how} are bitwise combinations of zero or one
+"rounding instructions" with zero or one "denominator types".
+
+Rounding instructions control how fractional parts in the specified
+denominator affect the result. For example, if a computed result is
+"3/4" but the specified denominator for the return value is 2, should
+the return value be "1/2" or "2/2"?
+
+Possible rounding instructions are:
+
+ at table @code
+
+ at item GNC_RND_FLOOR
+Round toward -infinity
+
+ at item GNC_RND_CEIL
+Round toward +infinity
+
+ at item GNC_RND_TRUNC
+Truncate fractions (round toward zero)
+
+ at item GNC_RND_PROMOTE
+Promote fractions (round away from zero)
+
+ at item GNC_RND_ROUND
+Use unbiased ("banker's") rounding. This rounds to the nearest integer,
+and to the nearest even integer when there are two equidistant nearest
+integers. This is generally the one you should use for financial
+quantities.
+
+ at item GNC_RND_ROUND_HALF_UP
+Round to the nearest integer, rounding away from zero when there are two
+equidistant nearest integers.
+
+ at item GNC_RND_ROUND_HALF_DOWN
+Round to the nearest integer, rounding toward zero when there are two
+equidistant nearest integers.
+
+ at item GNC_RND_NEVER
+Never round at all, and signal an error if there is a fractional result
+in a computation.
+
+ at end table
+
+
+The denominator type specifies how to compute a denominator if
+ at code{GNC_DENOM_AUTO} is specified as the @var{denom}. Valid denominator
+types are:
+
+ at table @code
+
+ at item GNC_DENOM_EXACT
+Use any denominator which gives an exactly correct ratio of numerator to
+denominator. Use EXACT when you do not wish to lose any information in
+the result but also do not want to spend any time finding the "best"
+denominator.
+
+ at item GNC_DENOM_REDUCE
+Reduce the result value by common factor elimination, using the smallest
+possible value for the denominator that keeps the correct ratio. The
+numerator and denominator of the result are relatively prime. This can
+be computationally expensive for large fractions.
+
+ at item GNC_DENOM_LCD
+Find the least common multiple of the arguments' denominators and use
+that as the denominator of the result.
+
+ at item GNC_DENOM_FIXED
+All arguments are required to have the same denominator, that
+denominator is to be used in the output, and an error is to be signaled
+if any argument has a different denominator.
+
+ at item GNC_DENOM_SIGFIG
+Round to the number of significant figures given in the rounding
+instructions by the GNC_DENOM_SIGFIGS () macro.
+
+ at item GNC_DENOM_SIGFIGS (n)
+Use a value for the denominator that will keep at least @code{n}
+significant figures in the result.
+
+ at end table
+
+
+To use traditional rational-number operational semantics (all results
+are exact and are reduced to relatively-prime fractions) pass the
+argument @code{GNC_DENOM_AUTO} as @var{denom} and @code{GNC_DENOM_REDUCE
+| GNC_RND_NEVER} as @var{how}.
+
+To enforce strict financial semantics (such that all operands must have
+the same denominator as each other and as the result), use
+ at var{GNC_DENOM_AUTO} as @var{denom} and @code{GNC_DENOM_FIXED |
+GNC_RND_NEVER} as @var{how}.
+
+
+ at node Creating Numeric Objects, Basic Arithmetic Operations, Standard Numeric Arguments, Numeric Library
+
+=============== The documentation below for gnc_numeric is obsolete
+ and has been superseeded by the gnc_numeric docs in the header file.
+=========================================
+
+ at subsection Creating Numeric Objects
+ at cindex Creating Numeric Objects
+
+ at deftypefun gnc_numeric gnc_numeric_create (int @var{num}, int @var{denom})
+Create a @code{gnc_numeric} object with a value of "@var{num} / @var{denom}".
+ at end deftypefun
+
+ at deftypefun gnc_numeric gnc_numeric_zero ()
+Create a @code{gnc_numeric} object with a value of 0.
+ at end deftypefun
+
+
+ at node Basic Arithmetic Operations, Numeric Comparisons and Predicates, Creating Numeric Objects, Numeric Library
+ at subsection Basic Arithmetic Operations
+ at cindex Basic Arithmetic Operations
+
+See @ref{Standard Numeric Arguments} for a description of the @var{denom}
+and @var{how} arguments to each arithmetic function.
+
+ at deftypefun gnc_numeric gnc_numeric_add (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how})
+Return the sum of @var{a} and @var{b}.
+ at end deftypefun
+
+ at deftypefun gnc_numeric gnc_numeric_sub (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how})
+Return "@var{a} - @var{b}".
+ at end deftypefun
+
+ at deftypefun gnc_numeric gnc_numeric_mul (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how})
+Return the product of @var{a} and @var{b}.
+ at end deftypefun
+
+ at deftypefun gnc_numeric gnc_numeric_div (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how})
+Return "@var{a} / @var{b}".
+ at end deftypefun
+
+ at deftypefun gnc_numeric gnc_numeric_neg (gnc_numeric @var{a})
+Return "- at var{a}".
+ at end deftypefun
+
+ at deftypefun gnc_numeric gnc_numeric_abs (gnc_numeric @var{a})
+Return the absolute value of @var{a}.
+ at end deftypefun
+
+ at deftypefun gnc_numeric gnc_numeric_add_fixed (gnc_numeric @var{a}, gnc_numeric @var{b})
+Equivalent to @code{gnc_numeric_add} on @var{a} and @var{b} with
+ at code{GNC_DENOM_AUTO} for @var{denom} and @code{GNC_DENOM_FIXED |
+GNC_RND_NEVER} for @var{how}.
+ at end deftypefun
+
+ at deftypefun gnc_numeric gnc_numeric_sub_fixed (gnc_numeric @var{a}, gnc_numeric @var{b})
+Equivalent to @code{gnc_numeric_sub} on @var{a} and @var{b} with
+ at code{GNC_DENOM_AUTO} for @var{denom} and @code{GNC_DENOM_FIXED |
+GNC_RND_NEVER} for @var{how}.
+ at end deftypefun
+
+ at deftypefun gnc_numeric gnc_numeric_add_with_error (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how}, {gnc_numeric *} @var{error})
+The same as @code{gnc_numeric_add}, but uses @var{error} for accumulating
+conversion roundoff error.
+ at end deftypefun
+
+ at deftypefun gnc_numeric gnc_numeric_sub_with_error (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how}, {gnc_numeric *} @var{error})
+The same as @code{gnc_numeric_sub}, but uses @var{error} for accumulating
+conversion roundoff error.
+ at end deftypefun
+
+ at deftypefun gnc_numeric gnc_numeric_mul_with_error (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how}, {gnc_numeric *} @var{error})
+The same as @code{gnc_numeric_mul}, but uses @var{error} for accumulating
+conversion roundoff error.
+ at end deftypefun
+
+ at deftypefun gnc_numeric gnc_numeric_div_with_error (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how}, {gnc_numeric *} @var{error})
+The same as @code{gnc_numeric_div}, but uses @var{error} for accumulating
+conversion roundoff error.
+ at end deftypefun
+
+
+ at node Numeric Comparisons and Predicates, Numeric Denominator Conversion, Basic Arithmetic Operations, Numeric Library
+ at subsection Numeric Comparisons and Predicates
+ at cindex Numeric Comparisons and Predicates
+
+ at deftypefun int gnc_numeric_zero_p (gnc_numeric @var{a})
+Returns 1 if @code{@var{a} == 0}, otherwise returns 0.
+ at end deftypefun
+
+ at deftypefun int gnc_numeric_positive_p (gnc_numeric @var{a})
+Returns 1 if @code{@var{a} > 0}, otherwise returns 0.
+ at end deftypefun
+
+ at deftypefun int gnc_numeric_negative_p (gnc_numeric @var{a})
+Returns 1 if @code{@var{a} < 0}, otherwise returns 0.
+ at end deftypefun
+
+ at deftypefun int gnc_numeric_compare (gnc_numeric @var{a}, gnc_numeric @var{b})
+Returns +1 if @code{@var{a} > @var{b}}, -1 if @code{@var{b} > @var{a}}, 0 if @code{@var{a} == @var{b}}.
+ at end deftypefun
+
+ at deftypefun int gnc_numeric_eq (gnc_numeric @var{a}, gnc_numeric @var{b})
+Returns 1 if @code{numerator(@var{a}) == numerator(@var{b})} and
+ at code{denominator(@var{a}) == denominator(@var{b})}, otherwise returns 0.
+ at end deftypefun
+
+ at deftypefun int gnc_numeric_equal (gnc_numeric @var{a}, gnc_numeric @var{b})
+Returns 1 if the fraction represented by @var{a} is equal to the fraction
+represented by @var{b}, otherwise returns 0.
+ at end deftypefun
+
+ at deftypefun int gnc_numeric_same (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how})
+Convert both @var{a} and @var{b} to @var{denom} (@pxref{Standard Numeric
+Arguments} and compare numerators of the result.
+
+ at example
+ For example, if @code{@var{a} == 7/16} and @code{@var{b} == 3/4},
+ @code{gnc_numeric_same(@var{a}, @var{b}, 2, GNC_RND_TRUNC) == 1}
+ because both 7/16 and 3/4 round to 1/2 under truncation. However,
+ @code{gnc_numeric_same(@var{a}, @var{b}, 2, GNC_RND_ROUND) == 0}
+ because 7/16 rounds to 1/2 under unbiased rounding but 3/4 rounds
+ to 2/2.
+ at end example
+ at end deftypefun
+
+
+ at node Numeric Denominator Conversion, Numeric Floating Point Conversion, Numeric Comparisons and Predicates, Numeric Library
+=============== The documentation below for gnc_numeric is obsolete
+ and has been superseeded by the gnc_numeric docs in the header file.
+=========================================
+
+ at subsection Numeric Denominator Conversion
+ at cindex Numeric Denominator Conversion
+
+ at deftypefun gnc_numeric gnc_numeric_convert (gnc_numeric @var{in}, gint64 @var{denom}, gint @var{how})
+Convert @var{in} to the specified denominator under standard arguments
+ at var{denom} and @var{how}. @xref{Standard Numeric Arguments}.
+ at end deftypefun
+
+ at deftypefun gnc_numeric gnc_numeric_convert_with_error (gnc_numeric @var{in}, gint64 @var{denom}, gint @var{how}, {gnc_numeric *} @var{error})
+Same as @code{gnc_numeric_convert}, but return a remainder value for
+accumulating conversion error.
+ at end deftypefun
+
+ at deftypefun gnc_numeric gnc_numeric_reduce (gnc_numeric @var{in})
+Return @var{in} reduced by GCF reduction.
+ at end deftypefun
+
+
+ at node Numeric Floating Point Conversion, Numeric String Conversion, Numeric Denominator Conversion, Numeric Library
+ at subsection Numeric Floating Point Conversion
+ at cindex Numeric Floating Point Conversion
+
+ at deftypefun gnc_numeric double_to_gnc_numeric (double @var{arg}, gint64 @var{denom}, gint @var{how})
+Convert a floating-point number to a @code{gnc_numeric}. Both @var{denom}
+and @var{how} are used as in arithmetic, but @code{GNC_DENOM_AUTO} is
+not recognized.
+ at end deftypefun
+
+ at deftypefun double gnc_numeric_to_double (gnc_numeric @var{arg})
+Convert @var{arg} to a @code{double} value.
+ at end deftypefun
+
+
+ at node Numeric String Conversion, Numeric Error Handling , Numeric Floating Point Conversion, Numeric Library
+ at subsection Numeric String Conversion
+ at cindex Numeric String Conversion
+
+ at deftypefun {gchar *} gnc_numeric_to_string (gnc_numeric @var{n})
+Return a string representation of @var{n}. The string must be
+freed with @code{g_free}.
+ at end deftypefun
+
+ at deftypefun {const gchar *} string_to_gnc_numeric (const {gchar *} @var{str}, {gnc_numeric *} @var{n})
+Read a @code{gnc_numeric} from @var{str}, skipping any leading
+whitespace, and returning a pointer to just past the last byte
+read. Return NULL on error.
+ at end deftypefun
+
+
+ at node Numeric Error Handling , Numeric Example, Numeric String Conversion, Numeric Library
+ at subsection Numeric Error Handling
+ at cindex Numeric Error Handling
+
+ at deftypefun int gnc_numeric_check (gnc_numeric @var{num})
+Check @var{num} for the possibility that it is an error signal rather
+than a proper value. Possible return codes are:
+
+ at table @code
+
+ at item GNC_ERROR_OK
+No error condition
+
+ at item GNC_ERROR_ARG
+An improper argument was passed to a function
+
+ at item GNC_ERROR_OVERFLOW
+An overflow occurred while calculating a result
+
+ at item GNC_ERROR_DENOM_DIFF
+ at code{GNC_DENOM_FIXED} was specified, but argument denominators differed.
+
+ at item GNC_ERROR_REMAINDER
+ at code{GNC_RND_NEVER} was specified, but the result could not be
+converted to the desired denominator without a remainder.
+
+ at end table
+
+ at end deftypefun
+
+ at deftypefun gnc_numeric gnc_numeric_error (int error_code)
+Create a @code{gnc_numeric} object that signals the error condition
+noted by @var{error_code} rather than a number.
+ at end deftypefun
+
+
+ at node Numeric Example, , Numeric Error Handling , Numeric Library
+ at subsection Numeric Example
+ at cindex Numeric Example
+
+=============== The documentation below for gnc_numeric is obsolete
+ and has been superseeded by the gnc_numeric docs in the header file.
+=========================================
+
+The following program finds the best @code{gnc_numeric} approximation to
+the @file{math.h} constant @code{M_PI} given a maximum denominator. For
+large denominators, the @code{gnc_numeric} approximation is accurate to
+more decimal places than will generally be needed, but in some cases
+this may not be good enough. For example,
+
+ at example
+ M_PI = 3.14159265358979323846
+ 245850922 / 78256779 = 3.14159265358979311599 (16 sig figs)
+ 3126535 / 995207 = 3.14159265358865047446 (12 sig figs)
+ 355 / 113 = 3.14159292035398252096 (7 sig figs)
+ at end example
+
+ at example
+#include <glib.h>
+#include "gnc-numeric.h"
+#include <math.h>
+
+int
+main(int argc, char ** argv)
+@{
+ gnc_numeric approx, best;
+ double err, best_err=1.0;
+ double m_pi = M_PI;
+ gint64 denom;
+ gint64 max;
+
+ sscanf(argv[1], "%Ld", &max);
+
+ for (denom = 1; denom < max; denom++)
+ @{
+ approx = double_to_gnc_numeric (m_pi, denom, GNC_RND_ROUND);
+ err = m_pi - gnc_numeric_to_double (approx);
+ if (fabs (err) < fabs (best_err))
+ @{
+ best = approx;
+ best_err = err;
+ printf ("%Ld / %Ld = %.30f\n", gnc_numeric_num (best),
+ gnc_numeric_denom (best), gnc_numeric_to_double (best));
+ @}
+ @}
+@}
+ at end example
+
+
+ at node Key-Value Pair Frames, Events, Numeric Library, Engine
+ at section Key-Value Pair Frames
+ at cindex Key-Value Pairs
+
+The number and types of data items which are associated with the
+financial abstractions (Accounts, Transactions, and Splits) can vary
+widely. For example, an Account which represents a user's checking
+account might need to store the bank name, a telephone number, and a
+username for online banking purposes. Another Account representing the
+user's ownership of a stock might need to store information about
+retrieving price quotes online such as the ticker symbol and the
+exchange.
+
+To meet this need for varying data storage, the GnuCash accounting
+entities use Key-Value Pair Frames (hereafter referred to as the
+datatype @code{kvp_frame}). A @code{kvp_frame} is a set of associations
+between character strings (keys) and @code{kvp_value} structures. A
+ at code{kvp_value} is a union with possible types enumerated in the
+ at code{kvp_value_t} enum which indicates the type of data stored in a
+ at code{kvp_value} object.
+
+ at menu
+* Key-Value Policy::
+* kvp_frame::
+* kvp_value::
+* kvp_list::
+ at end menu
+
+
+ at node Key-Value Policy, kvp_frame, Key-Value Pair Frames, Key-Value Pair Frames
+ at subsection Key-Value Policy
+ at cindex Key-Value Policy
+
+This section defines the policy that programmers should follow
+when using key-value pairs to store information. Because of the
+large amount of information which can potentially be stored using
+this mechanism, it is important to follow these guidelines so
+that order will be maintained.
+
+The following rules should be followed for using key-value pairs:
+
+ at itemize
+
+ at item
+The document @file{src/engine/kvp_doc.txt} should be used to document the
+use of keys and values. Please consult this document before planning any
+use of new keys.
+
+ at item
+Key strings should be in all lower case with the '-' character
+separating words. If possible, use only alphanumeric characters and
+'-'. Example: @code{bank-info}. Because the '/' character is useful for
+describing keys in sub-frames (@code{bank-info/routing-number}), do not
+use the '/' character in key names.
+
+ at item
+Favor longer, descriptive key strings over short ones. Example:
+ at code{online-banking-info} is better than @code{onln-bnk}.
+
+ at item
+Make use of the fact that frames can be stored in frames. If a group
+of keys are used for a related purpose, consider storing them together
+in a sub-frame.
+
+ at item
+Values should generally not be accessed directly through keys, but
+should rather be accessed through specific API calls. The API calls
+do not necessarily need to part a part of the Engine API. For example,
+the GUI would probably define keys that the Engine does not need to
+know about.
+
+ at item
+The same key should not be used for different engine structures (Accounts,
+Transactions, Splits), unless the key's value has the same type and the
+same basic purpose.
+
+ at end itemize
+
+
+ at node kvp_frame, kvp_value, Key-Value Policy, Key-Value Pair Frames
+ at subsection kvp_frame
+ at tindex kvp_frame
+
+A @code{kvp_frame} is the datatype used to associate key strings with
+ at code{kvp_value} objects (@pxref{kvp_value}).
+
+ at deftypefun kvp_frame* kvp_frame_new (void)
+Create and initialize a new @code{kvp_frame} object and return
+a pointer to it.
+ at end deftypefun
+
+ at deftypefun void kvp_frame_delete (kvp_frame * @var{frame})
+Free all memory associated with @var{frame}.
+ at end deftypefun
+
+ at deftypefun kvp_frame* kvp_frame_copy (const kvp_frame * frame)
+Return a deep copy of @var{frame}.
+ at end deftypefun
+
+ at deftypefun void kvp_frame_set_slot (kvp_frame * @var{frame}, const char * @var{key}, const kvp_value * @var{value})
+Associate @var{key} with @var{value} in @var{frame}.
+ at end deftypefun
+
+ at deftypefun void kvp_frame_set_slot_nc (kvp_frame * @var{frame}, const char * @var{key}, kvp_value * @var{value})
+Same as @code{kvp_frame_set_slot}, except that @var{value} is used
+directly, instead of being copied. This call transfers 'ownership'
+of @var{value} to @var{frame}.
+ at end deftypefun
+
+ at deftypefun kvp_value* kvp_frame_get_slot (kvp_frame * @var{frame}, const char * @var{key})
+Return the @code{kvp_value} object associated with @var{key}
+in @var{frame} or return @code{NULL} if there is no association
+for @var{key}. The value returned is not a copy.
+ at end deftypefun
+
+ at deftypefun void kvp_frame_set_slot_path (kvp_frame * @var{frame}, const kvp_value * @var{value}, const char * @var{first_key}, ...)
+Associate @var{value} with the ``key path'' specified by the variable
+argument list. Each key in the path except the last denotes a sub-frame
+which is associated with the given key. The variable list must be
+terminated with NULL.
+ at end deftypefun
+
+ at deftypefun void kvp_frame_set_slot_path_gslist (kvp_frame * @var{frame}, const kvp_value * @var{value}, GSList * @var{key_path})
+The same as @code{kvp_frame_set_slot_path}, except that the key path is
+specified using a GSList. All the keys in the list should be non-NULL.
+ at end deftypefun
+
+ at deftypefun {kvp_value *} kvp_frame_get_slot_path (kvp_frame * @var{frame}, const char * @var{first_key}, ...)
+Return the value associated with the key path, or @code{NULL} if none.
+The path is specified as in @code{kvp_frame_set_slot_path}.
+ at end deftypefun
+
+ at deftypefun {kvp_value *} kvp_frame_get_slot_path_gslist (kvp_frame * @var{frame}, GSList * @var{key_path})
+Return the value associated with the key path, or @code{NULL} if none.
+The path is specified as in @code{kvp_frame_set_slot_path_gslist}.
+ at end deftypefun
+
+ at deftypefun {kvp_frame *} kvp_frame_get_frame (kvp_frame * @var{frame}, ...)
+Works like @code{kvp_frame_get_slot_path}, but returns the last frame
+in the path. All the keys should refer to frames. If the frame path
+does not exist, it is created.
+ at end deftypefun
+
+ at deftypefun {kvp_frame *} kvp_frame_get_frame_gslist (kvp_frame * @var{frame}, GSList * @var{key_path})
+Works like @code{kvp_frame_get_slot_path_gslist}, but returns the last
+frame in the path. All the keys should refer to frames. If the frame
+path does not exist, it is created.
+ at end deftypefun
+
+ at deftypefun {kvp_frame *} kvp_frame_get_frame_slash (kvp_frame * @var{frame}, const char * @var{path})
+Works like @code{kvp_frame_get_frame}, but the frame path is specified
+as a single string where the keys are separated by slashes; thus, for
+example: @code{/this/is/a/valid/path} and @code{///so//is////this/}.
+Multiple slashes are compresed and a leading slash is optional. The
+pointers @code{.} and @code{..} are @emph{not} followed/obeyed. (This
+is arguably a bug that needs fixing).
+ at end deftypefun
+
+
+ at node kvp_value, kvp_list, kvp_frame, Key-Value Pair Frames
+ at subsection kvp_value
+ at tindex kvp_value
+ at tindex kvp_value_t
+
+The @code{kvp_value} object stores the 'value' part of a key-value
+association in a @code{kvp_frame} object.
+
+ at deftypefun void kvp_value_delete (kvp_value * @var{value})
+Free all of the memory associated with @var{value}.
+ at end deftypefun
+
+ at deftypefun kvp_value* kvp_value_copy (const kvp_value * @var{value})
+Return a deep copy of @var{value}.
+ at end deftypefun
+
+ at deftypefun kvp_value_t kvp_value_get_type (const kvp_value * @var{value})
+Return the type of value stored in @var{value}.
+ at end deftypefun
+
+A @code{kvp_value_t} enum must have one of the following values:
+
+ at table @code
+
+ at item KVP_TYPE_NONE
+Indicates the abscence of a value in a @code{kvp_frame}.
+
+ at item KVP_TYPE_INT64
+A @code{gint64} value.
+
+ at item KVP_TYPE_FLOAT64
+A @code{double} value.
+
+ at item KVP_TYPE_STRING
+A @code{char *} value of arbitrary length.
+
+ at item KVP_TYPE_GUID
+A @code{GUID} value. @xref{Globally Unique Identifiers}.
+
+ at item KVP_TYPE_BINARY
+Arbitrary binary data.
+
+ at item KVP_TYPE_LIST
+A @code{kvp_list} item which contains a list of @code{kvp_value} items.
+
+ at item KVP_TYPE_FRAME
+A @code{kvp_frame} object. Thus, frames may contain other frames in a
+recursive manner.
+
+ at end table
+
+ at subsubsection Value Constructors
+
+The following functions create and return @code{kvp_value} objects with
+particular values. In the case of pointer arguments, deep copies are
+performed.
+
+ at deftypefun kvp_value* kvp_value_new_int64 (gint64 @var{value})
+ at end deftypefun
+ at deftypefun kvp_value* kvp_value_new_float64 (double @var{value})
+ at end deftypefun
+ at deftypefun kvp_value* kvp_value_new_string (const char * @var{value})
+ at end deftypefun
+ at deftypefun kvp_value* kvp_value_new_guid (const GUID * @var{guid})
+ at end deftypefun
+ at deftypefun kvp_value* kvp_value_new_binary (const void * @var{data}, int @var{datasize})
+ at end deftypefun
+ at deftypefun kvp_value* kvp_value_new_list (const kvp_list * @var{value})
+ at end deftypefun
+ at deftypefun kvp_value* kvp_value_new_frame (const kvp_frame * @var{value});
+ at end deftypefun
+
+ at subsubsection Value Accessors
+
+The following functions access the value of a given @code{kvp_value}
+object. If the type of the object does not correspond to that named
+in the function, @code{NULL}, @code{0}, or @code{0.0} is returned
+as appropriate.
+
+ at deftypefun gint64 kvp_value_get_int64 (const kvp_value * @var{value})
+ at end deftypefun
+ at deftypefun double kvp_value_get_float64 (const kvp_value * @var{value})
+ at end deftypefun
+ at deftypefun char* kvp_value_get_string (const kvp_value * @var{value})
+ at end deftypefun
+ at deftypefun GUID* kvp_value_get_guid (const kvp_value * @var{value})
+ at end deftypefun
+ at deftypefun void* kvp_value_get_binary (const kvp_value * @var{value}, int * @var{size_return})
+ at end deftypefun
+ at deftypefun kvp_list* kvp_value_get_list (const kvp_value * @var{value})
+ at end deftypefun
+ at deftypefun kvp_frame* kvp_value_get_frame (const kvp_value * @var{value})
+ at end deftypefun
+
+
+ at node kvp_list, , kvp_value, Key-Value Pair Frames
+ at subsection kvp_list
+ at tindex kvp_list
+
+A @code{kvp_list} object abstract a list of @code{kvp_value} objects.
+
+ at deftypefun kvp_list* kvp_list_new ()
+Return a newly allocated @code{kvp_list} object.
+ at end deftypefun
+
+ at deftypefun void kvp_list_delete (kvp_list * @var{list})
+Free all memory associated with @var{list}, including the
+ at code{kvp_value} objects in @var{list}.
+ at end deftypefun
+
+ at deftypefun kvp_list* kvp_list_copy (const kvp_list * @var{list})
+Return a deep copy of @var{list}.
+ at end deftypefun
+
+ at deftypefun gboolean kvp_list_null_p (const kvp_list * @var{list})
+Return @code{TRUE} if @var{list} is the empty list.
+ at end deftypefun
+
+ at deftypefun kvp_value* kvp_list_car (kvp_list * @var{list})
+If @var{list} is @code{NULL} or the empty list, return @code{NULL}.
+Otherwise, return the first @code{kvp_value} object in the list.
+ at end deftypefun
+
+ at deftypefun kvp_list* kvp_list_cdr (kvp_list * @var{list})
+If @var{list} is @code{NULL} or the empty list, return @code{NULL}.
+Otherwise, return a @code{kvp_list} object consisting of @var{list}
+with the first value removed. NOTE: the returned list is not a copy!
+ at end deftypefun
+
+ at deftypefun kvp_list* kvp_list_cons (kvp_value * @var{car}, kvp_list * @var{cdr})
+If either @var{car} or @var{cdr} is @code{NULL}, return @code{NULL}. Otherwise,
+return a @code{kvp_list} object consisting of the value of @var{car} followed
+by the values of @var{cdr}. This function uses 'hand-over' semantics, i.e.,
+the arguments @var{car} and @var{cdr} are no longer the responsibility of
+the caller and should not be accessed after the function returns.
+ at end deftypefun
+
+
+ at node Events, Commodities, Key-Value Pair Frames, Engine
+ at section Events
+
+The Engine supports the concept of @dfn{Events} which notify
+external code when engine entities are created, modified, or
+destroyed.
+
+User code can register event handers which are invoked for each event,
+giving information about the specific engine entity generating the event
+and the nature of the event (creation, modification, or deletion).
+
+
+ at menu
+* Event API::
+ at end menu
+
+
+ at node Event API, , Events, Events
+ at subsection Event API
+ at tindex GNCEngineEventType
+
+Engine events are classified using the @code{GNCEngineEventType}
+bitmask which has the following predefined values:
+
+ at table @code
+
+ at item GNC_EVENT_NONE
+A null value.
+
+ at item GNC_EVENT_CREATE
+Indicates an entity has been created.
+
+ at item GNC_EVENT_MODIFY
+Indicates an entity has been changed in some way.
+
+ at item GNC_EVENT_DESTROY
+Indicates an entity is being destroyed.
+
+ at item GNC_EVENT_ALL
+The boolean OR of @code{GNC_EVENT_CREATE}, @code{GNC_EVENT_MODIFY},
+and @code{GNC_EVENT_DESTROY}.
+
+ at end table
+
+Event handlers are functions with the following type:
+
+ at deftp {Data type} GNCEngineEventHandler void (*) (GUID * @var{entity}, GNCEngineEventType @var{event_type}, gpointer @var{user_data})
+A callback invoked when an engine event occurs. @var{entity} is the
+ at code{GUID} of the entity generating the event. @var{event_type} is
+one of @code{GNC_EVENT_CREATE}, @code{GNC_EVENT_MODIFY}, or
+ at code{GNC_EVENT_DESTROY}. @var{user_data} is the user data parameter
+supplied when the handler was registered.
+ at end deftp
+
+ at deftypefun gint gnc_engine_register_event_handler (GNCEngineEventHandler @var{handler}, gpointer @var{user_data})
+Register a handler for engine events. The return value is an identifier used
+to specify this handler in other API calls.
+ at end deftypefun
+
+ at deftypefun void gnc_engine_unregister_event_handler (gint @var{handler_id})
+Unregister the event handler specified by @var{handler_id}.
+ at end deftypefun
+
+ at deftypefun void gnc_engine_suspend_events (void)
+Suspend all engine events. This function may be called multiple
+times. To resume event generation, an equal number of calls to
+ at code{gnc_engine_resume_events} must be made.
+ at end deftypefun
+
+ at deftypefun void gnc_engine_resume_events (void)
+Resume engine event generation.
+ at end deftypefun
+
+
+ at node Commodities, Commodity Tables, Events, Engine
+ at section Commodities
+ at tindex gnc_commodity
+
+A Commodity is the Engine abstraction of a tradable quantity,
+like a national currency or shares of a stock. A commodity
+object contains the following pieces of information:
+
+ at table @asis
+
+ at item A mnemonic name
+The `short' name for the commodity. For national currencies
+this is the 3-letter ISO4217 code (USD, AUD, etc.). For stocks
+this is generally the exchange symbol (RHAT, IBM, etc.).
+
+ at item A namespace
+A string identifying the context in which the mnemonic is meaninful.
+
+ at item A full name
+The `long' name for the commodity, such as "US Dollar" or "IBM Common
+Stock".
+
+ at item A printable name
+The name used to print out a string describing the commodity to
+a user. This name is generally long -- in some contexts it may
+be better to use the mnemonic instead. The printable name is
+determined by the namespace and mnemonic.
+
+ at item A unique name
+A canonical name for the commodity that cannot be identical to
+another commodity's unique name. The unique name is determined
+by the namespace and mnemonic.
+
+ at item An exchange code
+A code used to identify the commodity in its namespace context.
+For example, stocks have a unique code assigned to them by the
+exchange they are listed on.
+
+ at item A fraction
+An integer N which specifies that 1/N is generally the smallest
+fraction of the commodity which can be traded. For example, most
+currencies are tradable in 1/100ths, so the fraction would be 100.
+
+ at end table
+
+ at menu
+* General Commodity API::
+* Commodity Getters::
+* Commodity Setters::
+ at end menu
+
+
+ at node General Commodity API, Commodity Getters, Commodities, Commodities
+ at subsection General Commodity API
+
+ at deftypefun {gnc_commodity *} gnc_commodity_new (const char * @var{fullname}, const char * @var{namespace}, const char * @var{mnemonic}, const char * @var{exchange_code}, int @var{fraction})
+Create and return a new commodity object with the given values, or
+ at code{NULL} if any of the values are invalid.
+ at end deftypefun
+
+ at deftypefun void gnc_commodity_destroy (gnc_commodity * @var{cm})
+Destroy the given commodity and free all associated memory.
+ at end deftypefun
+
+ at deftypefun gboolean gnc_commodity_equiv (const gnc_commodity * @var{a}, const gnc_commodity * @var{b})
+Return true if the two given commodities are equivalent. Two commodities
+are equivalent when they have the same namespace and the same mnemonic.
+ at end deftypefun
+
+
+ at node Commodity Getters, Commodity Setters, General Commodity API, Commodities
+ at subsection Commodity Getters
+
+ at deftypefun {const char *} gnc_commodity_get_mnemonic (const gnc_commodity * @var{cm})
+Return the mnemonic of @var{cm}.
+ at end deftypefun
+
+ at deftypefun {const char *} gnc_commodity_get_namespace (const gnc_commodity * @var{cm})
+Return the namespace of @var{cm}.
+ at end deftypefun
+
+ at deftypefun {const char *} gnc_commodity_get_fullname (const gnc_commodity * @var{cm})
+Return the full name of @var{cm}.
+ at end deftypefun
+
+ at deftypefun {const char *} gnc_commodity_get_printname (const gnc_commodity * @var{cm})
+Return the print name of @var{cm}.
+ at end deftypefun
+
+ at deftypefun {const char *} gnc_commodity_get_exchange_code (const gnc_commodity * @var{cm})
+Return the exchange code of @var{cm}.
+ at end deftypefun
+
+ at deftypefun {const char *} gnc_commodity_get_unique_name (const gnc_commodity * @var{cm})
+Return the unique name of @var{cm}.
+ at end deftypefun
+
+ at deftypefun int gnc_commodity_get_fraction (const gnc_commodity * @var{cm})
+Return the smallest tradable fraction of @var{cm}.
+ at end deftypefun
+
+
+ at node Commodity Setters, , Commodity Getters, Commodities
+ at subsection Commodity Setters
+
+ at deftypefun void gnc_commodity_set_mnemonic (gnc_commodity * @var{cm}, const char * @var{mnemonic})
+Set the mnemonic of @var{cm} to @var{mnemonic}.
+ at end deftypefun
+
+ at deftypefun void gnc_commodity_set_namespace (gnc_commodity * @var{cm}, const char * @var{namespace})
+Set the namespace of @var{cm} to @var{namespace}.
+ at end deftypefun
+
+ at deftypefun void gnc_commodity_set_fullname (gnc_commodity * @var{cm}, const char * @var{fullname})
+Set the fullname of @var{cm} to @var{fullname}.
+ at end deftypefun
+
+ at deftypefun void gnc_commodity_set_exchange_code (gnc_commodity * @var{cm}, const char * @var{exchange_code})
+Set the exchange code of @var{cm} to @var{exchange_code}.
+ at end deftypefun
+
+ at deftypefun void gnc_commodity_set_fraction (gnc_commodity * @var{cm}, int @var{smallest_fraction})
+Set the fraction of @var{cm} to @var{fraction}.
+ at end deftypefun
+
+
+ at node Commodity Tables, Prices, Commodities, Engine
+ at section Commodity Tables
+ at tindex gnc_commodity_table
+
+A Commodity Table holds a set of commodities and allows user code
+to add, remove, and access the commodities in the table.
+
+There is a single, global Commodity Table used by the Engine.
+
+ at menu
+* General Commodity Table API::
+* Commodity Table Access API::
+* Commodity Table Modification API::
+ at end menu
+
+
+ at node General Commodity Table API, Commodity Table Access API, Commodity Tables, Commodity Tables
+ at subsection General Commodity Table API
+
+ at deftypefun {gnc_commodity_table *} gnc_commodity_table_new (void)
+Allocate and initialize a @code{gnc_commodity_table}. The returned
+table must be destroyed with @code{gnc_commodity_table_destroy}.
+ at end deftypefun
+
+ at deftypefun void gnc_commodity_table_destroy (gnc_commodity_table * @var{table})
+Destroy @var{table} and all associated resources, including all
+Commodity objects in the table.
+ at end deftypefun
+
+ at deftypefun {gnc_commodity_table *} gnc_engine_commodities (void)
+Return the global engine commodity table.
+ at end deftypefun
+
+
+ at node Commodity Table Access API, Commodity Table Modification API, General Commodity Table API, Commodity Tables
+ at subsection Commodity Table Access API
+
+ at deftypefun {gnc_commodity *} gnc_commodity_table_lookup (const gnc_commodity_table * @var{table}, const char * @var{namespace}, const char * @var{mnemonic})
+Look up a commodity in @var{table} given the namespace and the mnemonic.
+If no such commodity exists, @code{NULL} is returned.
+ at end deftypefun
+
+ at deftypefun {gnc_commodity *} gnc_commodity_table_find_full (const gnc_commodity_table * @var{table}, const char * @var{namespace}, const char * @var{fullnam}e)
+Look up a commodity in @var{table} given the namespace and the full name.
+If no such commodity exists, @code{NULL} is returned.
+ at end deftypefun
+
+ at deftypefun int gnc_commodity_table_has_namespace (const gnc_commodity_table * @var{table}, const char * @var{namespace})
+Return true if @var{table} has the namespace @var{namespace}.
+ at end deftypefun
+
+ at deftypefun guint gnc_commodity_table_get_size (gnc_commodity_table * @var{table})
+Return the total number of commodities stored in @var{table}.
+ at end deftypefun
+
+ at deftypefun guint gnc_commodity_table_get_number_of_namespaces (gnc_commodity_table * @var{table})
+Return the number of distinct namespaces in @var{table}.
+ at end deftypefun
+
+ at deftypefun {GList *} gnc_commodity_table_get_namespaces (const gnc_commodity_table * @var{table})
+Return a list of the distinct namespaces in @var{table}. The list should
+be freed with @code{g_list_free} but the namespaces should not be freed
+or modified.
+ at end deftypefun
+
+ at deftypefun {GList *} gnc_commodity_table_get_commodities (const gnc_commodity_table * @var{table}, const char * @var{namespace})
+Return a list of the commodities under @var{namespace} in @var{table}.
+The list should be freed with @code{g_list_free} but the commodities
+should not be freed.
+ at end deftypefun
+
+
+ at node Commodity Table Modification API, , Commodity Table Access API, Commodity Tables
+ at subsection Commodity Table Modification API
+
+ at deftypefun {gnc_commodity *} gnc_commodity_table_insert (gnc_commodity_table * @var{table}, gnc_commodity * @var{comm})
+Add commodity @var{comm} to @var{table}. If @var{comm}'s namespace is
+not in @var{table}, the namespace will be added. This function has
+hand-over semantics, i.e., @var{table} assumes responsibility for
+ at var{comm}. @var{comm} may even be destroyed by this call! The function
+returns the actual commodity added as a result of the call. It may not
+be the same object as @var{comm}, but will be equivalent to @var{comm}.
+ at end deftypefun
+
+ at deftypefun void gnc_commodity_table_remove (gnc_commodity_table * @var{table}, gnc_commodity * @var{comm})
+Remove the given commodity from @var{table}. @var{comm} is not modified
+or destroyed.
+ at end deftypefun
+
+ at deftypefun void gnc_commodity_table_add_namespace (gnc_commodity_table * @var{table}, const char * @var{namespace})
+Add @var{namespace} to @var{table}.
+ at end deftypefun
+
+ at deftypefun void gnc_commodity_table_delete_namespace (gnc_commodity_table * @var{table}, const char * @var{namespace})
+Delete @var{namespace} from @var{table} including all associated
+commodities.
+ at end deftypefun
+
+ at deftypefun void gnc_commodity_table_remove_non_iso (gnc_commodity_table * @var{table})
+Remove and destroy all commodities in @var{table} which are not in the
+ISO4217 namespace.
+ at end deftypefun
+
+
+ at node Prices, Price Databases, Commodity Tables, Engine
+ at section Prices
+ at tindex GNCPrice
+
+A Price is the Engine abstraction of an "instantaneous" price quote for a
+given commodity with respect to another commodity. For example, a given
+price might represent the value of LNUX in USD on 2001-02-03. A Price
+contains the following pieces of information:
+
+ at table @asis
+
+ at item A GUID
+A GUID uniquely identifying the GNCPrice.
+
+ at item A commodity
+The commodity being priced.
+
+ at item A currency
+The denomination of the value of the item being priced.
+
+ at item A value
+The value of the item being priced.
+
+ at item A time
+The time the price was valid.
+
+ at item A source
+A string describing the source of the quote. These strings will have a
+form like this: "Finance::Quote", "user:misc", "user:foo", etc. If the
+quote came from a user, as a matter of policy, you @emph{must} prefix
+the string you give with "user:". For now, the only other reserved
+values are "Finance::Quote" and "old-file-import".
+
+ at item A type
+A string describing the type of quote -- types possible right now are
+"bid", "ask", "last", "nav", and "unknown".
+
+ at end table
+
+
+ at menu
+* Price Implementation Details::
+* General Price API::
+* Price Getters::
+* Price Setters::
+ at end menu
+
+
+ at node Price Implementation Details, General Price API, Prices, Prices
+ at subsection Price Implementation Details
+
+For the source and type fields, @code{NULL} and the empty string are
+considered the same, so if one of these is the empty string then it
+might be @code{NULL} after a file save/restore.
+
+GNCPrices are reference counted. When you create a price or or clone
+one, the new price's reference count is set to 1. When you are finished
+with a price, call @code{gnc_price_unref}. If you hand the price pointer
+to some other code that needs to keep it, make sure it calls
+ at code{gnc_price_ref} to indicate its interest in that price, and calls
+ at code{gnc_price_unref} when it's finished with the price. For those
+unfamiliar with reference counting, basically each price stores an
+integer count which starts at 1 and is incremented every time someone
+calls @code{gnc_price_ref}. Conversely, the count is decremented every
+time someone calls @code{gnc_price_unref}. If the count ever reaches 0,
+the price is destroyed.
+
+All of the getters return data that's internal to the GNCPrice,
+not copies, so don't free or modify these values.
+
+All of the setters store copies of the data given, with the exception of
+the commodity field which just stores the pointer given. It is assumed
+that commodities are a global resource and are pointer unique.
+
+
+ at node General Price API, Price Getters, Price Implementation Details, Prices
+ at subsection General Price API
+
+ at deftypefun {GNCPrice *} gnc_price_create (void)
+Return a newly allocated and initialized price with a reference count of
+1. The price should be dereferenced with @code{gnc_price_unref} when no
+longer needed, but the price should not be freed by user code.
+ at end deftypefun
+
+ at deftypefun {GNCPrice *} gnc_price_clone (GNCPrice * @var{p})
+Return a newly allocated price that's a content-wise duplicate of
+ at var{p}. The returned clone will have a reference count of 1.
+ at end deftypefun
+
+ at deftypefun void gnc_price_ref (GNCPrice * @var{p})
+Increase the reference count of @var{p} by 1.
+ at end deftypefun
+
+ at deftypefun void gnc_price_unref (GNCPrice * @var{p})
+Decrease the reference coutn of @var{p} by 1. If the
+resulting count is 0, @var{p} will be destroyed.
+ at end deftypefun
+
+ at deftypefun {GNCPrice *} gnc_price_lookup (const GUID * @var{guid})
+Lookup and return the price associated with @var{guid}, or @code{NULL}
+if there is no such price.
+ at end deftypefun
+
+
+ at node Price Getters, Price Setters, General Price API, Prices
+ at subsection Price Getters
+
+ at deftypefun {const GUID *} gnc_price_get_guid (GNCPrice * @var{p})
+Return the GUID of @var{p}.
+ at end deftypefun
+
+ at deftypefun {gnc_commodity *} gnc_price_get_commodity (GNCPrice * @var{p})
+Return the commodity of @var{p}.
+ at end deftypefun
+
+ at deftypefun {gnc_commodity *} gnc_price_get_currency (GNCPrice * @var{p})
+Return the currency of @var{p}.
+ at end deftypefun
+
+ at deftypefun Timespec gnc_price_get_time (GNCPrice * @var{p})
+Return the time of @var{p}.
+ at end deftypefun
+
+ at deftypefun {const char *} gnc_price_get_source (GNCPrice * @var{p})
+Return the source of @var{p}.
+ at end deftypefun
+
+ at deftypefun {const char *} gnc_price_get_type (GNCPrice * @var{p})
+Return the type of @var{p}.
+ at end deftypefun
+
+ at deftypefun gnc_numeric gnc_price_get_value (GNCPrice * @var{p})
+Return the value of @var{p}.
+ at end deftypefun
+
+ at deftypefun gint32 gnc_price_get_version (GNCPrice * @var{p})
+Return the version of @var{p}.
+ at end deftypefun
+
+
+ at node Price Setters, , Price Getters, Prices
+ at subsection Price Setters
+
+Invocations of the setters should be wrapped with calls to
+ at code{gnc_price_begin_edit} and @code{gnc_price_commit_edit}. The
+begin/commit calls help ensure that the local price db is synchronized
+with the backend.
+
+ at deftypefun void gnc_price_begin_edit (GNCPrice * @var{p})
+Begin a sequence of changes to @var{p}.
+ at end deftypefun
+
+ at deftypefun void gnc_price_commit_edit (GNCPrice * @var{p})
+End a sequence of changes to @var{p}.
+ at end deftypefun
+
+ at deftypefun void gnc_price_set_commodity (GNCPrice * @var{p}, gnc_commodity * @var{c})
+Set the commodity of @var{p} to @var{c}.
+ at end deftypefun
+
+ at deftypefun void gnc_price_set_currency (GNCPrice * @var{p}, gnc_commodity * @var{c})
+Set the currency of @var{p} to @var{c}.
+ at end deftypefun
+
+ at deftypefun void gnc_price_set_time (GNCPrice * @var{p}, Timespec @var{t})
+Set the time of @var{p} to @var{t}.
+ at end deftypefun
+
+ at deftypefun void gnc_price_set_source (GNCPrice * @var{p}, const char * @var{source})
+Set the source of @var{p} to @var{source}.
+ at end deftypefun
+
+ at deftypefun void gnc_price_set_type (GNCPrice * @var{p}, const char * @var{type})
+Set the type of @var{p}to @var{type}.
+ at end deftypefun
+
+ at deftypefun void gnc_price_set_value (GNCPrice * @var{p}, gnc_numeric @var{value})
+Set the value of @var{p} to @var{value}.
+ at end deftypefun
+
+ at deftypefun void gnc_price_set_version (GNCPrice * @var{p}, gint32 @var{versn})
+Set the version of @var{p} to @var{versn}.
+ at end deftypefun
+
+
+ at node Price Databases, Splits, Prices, Engine
+ at section Price Databases
+ at tindex GNCPriceDB
+
+A Price Database stores GNCPrices and allows prices to be looked
+up based on currency, commodity, and time.
+
+
+ at menu
+* Price Lists::
+* General Price Database API::
+ at end menu
+
+
+ at node Price Lists, General Price Database API, Price Databases, Price Databases
+ at subsection Price Lists
+
+Price Lists are used by Price Databases to organize prices for a given
+commodity and currency. A Price List is a list of prices with the same
+commodity and currency, sorted by decreasing time (earlier prices come
+later in the list).
+
+ at deftypefun gboolean gnc_price_list_insert (GList ** @var{prices}, GNCPrice * @var{p})
+Insert price @var{p} into the list @var{prices}, calling
+ at var{gnc_price_ref} on @var{p} during the process.
+ at end deftypefun
+
+ at deftypefun gboolean gnc_price_list_remove (GList ** @var{prices}, GNCPrice * @var{p})
+Remove price @var{p} from the list @var{prices}, calling
+ at code{gnc_price_unref} on @var{p} during the process.
+ at end deftypefun
+
+ at deftypefun void gnc_price_list_destroy (GList * @var{prices})
+Destroy the price list @var{prices}, calling @code{gnc_price_unref}
+on all the prices in the list.
+ at end deftypefun
+
+
+ at node General Price Database API, , Price Lists, Price Databases
+ at subsection General Price Database API
+
+ at deftypefun {GNCPriceDB *} gnc_pricedb_create (void)
+Create and return a new price database.
+ at end deftypefun
+
+ at deftypefun void gnc_pricedb_destroy (GNCPriceDB * @var{db})
+Destroy the price database @var{db} and unreference all of
+the prices it contains. This may not deallocate all of those
+prices; other code may still be holding references to them.
+ at end deftypefun
+
+ at deftypefun gboolean gnc_pricedb_add_price (GNCPriceDB * @var{db}, GNCPrice * @var{p})
+Add the price @var{p} to @var{db}. This will increase the
+reference count of @var{p}, so user code may safely drop
+its reference to the price (i.e. call @code{gnc_price_unref})
+if the call succeeds (returns true).
+ at end deftypefun
+
+ at deftypefun gboolean gnc_pricedb_remove_price (GNCPriceDB * @var{db}, GNCPrice * @var{p})
+Removes the price @var{p} from the price database @var{db}. Returns true
+if successful and false otherwise.
+ at end deftypefun
+
+
+ at node Splits, Transactions, Price Databases, Engine
+ at section Splits
+ at tindex Split
+
+A Split is the Engine abstraction of an accounting entry in an Account
+Ledger. In accounting terms, a Split is a Ledger Entry. As such, it
+contains the following pieces of information:
+
+ at table @asis
+
+ at item A parent Account
+The Account of which it is an entry.
+
+ at item A parent Transaction.
+In accounting terms, this is the Journal Entry which this Ledger Entry
+is linked to.
+
+ at item A 'share quantity'
+This is the number of 'shares' which have been debited to the parent
+Account. This quantity may be negative, in which case the Split
+represents a 'credit'. Shares are given in units of the security of the
+Account, unless the security field is NULL, in which case shares are
+given in units of the Account currency. @xref{Accounts}.
+
+ at item A 'value'
+This represents the value of the shares in units of the currency of
+the Account. If the currency and the security are the same, or the
+security field is NULL, the value and share quantity must be equal.
+
+ at item A 'reconciled' flag
+This flag represents the reconciled status of the Split. Possible
+reconciliation states for a Split are:
+
+ @table @asis
+
+ @item Not Reconciled
+ The Split has not been reconciled or cleared.
+
+ @item Cleared
+ The Split has been cleared, but not reconciled.
+
+ @item Reconciled
+ The Split has been reconciled with a statement.
+
+ @item Frozen
+ The Split has been frozen into the accounting period.
+
+ @end table
+
+ at end table
+
+In addition to the above, Splits contain a Memo field, an Action
+field, and a key-value pair frame. The Memo and Action fields are for
+arbitrary user input. See src/engine/kvp_frame.txt for the names of
+keys that have already been reserved for use in the frame.
+
+
+ at menu
+* General Split API::
+* Split Getters::
+* Split Setters::
+ at end menu
+
+ at node General Split API, Split Getters, Splits, Splits
+ at subsection General Split API
+
+ at deftypefun {Split *} xaccMallocSplit (void)
+Allocate, initialize, and return a new Split.
+ at end deftypefun
+
+ at deftypefun void xaccSplitDestroy (Split * @var{split})
+Update @var{split}'s parent Account and Transaction in a consistent
+manner, completely unlinking of @var{split} and freeing its memory. The
+goal of this routine is to perform the removal and destruction of the
+Split in an atomic fashion, with no chance of accidentally leaving the
+accounting structure out-of-balance or otherwise inconsistent.
+
+If the deletion of the Split leaves the Transaction with no Splits, then
+the Transaction will be marked for deletion, but will not be deleted
+until the @code{xaccTransCommitEdit()} routine is called.
+ at end deftypefun
+
+ at deftypefun {const GUID *} xaccSplitGetGUID (Split * @var{split})
+Return the GUID of @var{split}.
+ at end deftypefun
+
+ at deftypefun {Split *} xaccSplitLookup (const GUID * @var{guid})
+Return the split associated with @var{GUID}, or @code{NULL} if there is
+no such split.
+ at end deftypefun
+
+ at deftypefun void xaccSplitMakeStockSplit (Split * @var{split})
+Modify @var{split} to be an ``official'' stock-split split. Among other
+things, this involves clearing the value of the split to 0.
+ at end deftypefun
+
+
+ at node Split Getters, Split Setters, General Split API, Splits
+ at subsection Split Getters
+
+ at deftypefun {Account *} xaccSplitGetAccount (Split * @var{split})
+Return the parent Account of @var{split}.
+ at end deftypefun
+
+ at deftypefun {Transaction *} xaccSplitGetParent (Split * @var{split})
+Return the parent Transaction of @var{split}.
+ at end deftypefun
+
+ at deftypefun gnc_numeric xaccSplitGetShareAmount (Split * @var{split})
+Return the 'share quantity' of @var{split}.
+ at end deftypefun
+
+ at deftypefun gnc_numeric xaccSplitGetSharePrice (Split * @var{split})
+Return the 'share price' of @var{split}, which is the value
+divided by the share quantity.
+ at end deftypefun
+
+ at deftypefun gnc_numeric xaccSplitGetValue (Split * @var{split})
+Return the value of @var{split}.
+ at end deftypefun
+
+ at deftypefun gnc_numeric xaccSplitGetBaseValue (Split * @var{split}, const char * @var{base_currency})
+Return either the share quantity or the value of @var{split}, depending
+upon whether @var{base_currency} matches the security or currency of the
+parent Account, respectively. No other value for @var{base_currency} is
+legal.
+ at end deftypefun
+
+ at deftypefun char xaccSplitGetReconcile (Split * @var{split})
+Return the value of the reconcile flag in @var{split}. Possible
+values for the flag are:
+
+ @table @code
+
+ @item NREC
+ Not Reconciled
+
+ @item CREC
+ Cleared
+
+ @item YREC
+ Reconciled
+
+ @item FREC
+ Frozen
+
+ @end table
+
+ at end deftypefun
+
+ at deftypefun void xaccSplitGetDateReconciledTS (Split * @var{split}, Timespec * @var{ts})
+Fill @var{ts} with the reconciled date of @var{split}.
+ at end deftypefun
+
+ at deftypefun {const char *} xaccSplitGetMemo (Split * @var{split})
+Return the Memo field of @var{split}.
+ at end deftypefun
+
+ at deftypefun {const char *} xaccSplitGetAction (Split * @var{split})
+Return the Action field of @var{split}.
+ at end deftypefun
+
+ at deftypefun gnc_numeric xaccSplitGetBalance (Split * @var{split})
+Return the balance of @var{split}'s parent Account up to and including
+ at var{split}. See @ref{Accounts} for details.
+ at end deftypefun
+
+ at deftypefun gnc_numeric xaccSplitGetClearedBalance (Split * @code{split})
+Return the cleared balance of @var{split}'s parent Account up to and
+including @var{split}. See @ref{Accounts} for details.
+ at end deftypefun
+
+ at deftypefun gnc_numeric xaccSplitGetReconciledBalance (Split * @code{split})
+Return the reconciled balance of @var{split}'s parent Account up to and
+including @var{split}. See @ref{Accounts} for details.
+ at end deftypefun
+
+ at deftypefun gnc_numeric xaccSplitGetShareBalance (Split * @var{split})
+Return the share balance of @var{split}'s parent Account up to and
+including @var{split}. See @ref{Accounts} for details.
+ at end deftypefun
+
+ at deftypefun gnc_numeric xaccSplitGetShareClearedBalance (Split * @code{split})
+Return the share cleared balance of @var{split}'s parent Account up to
+and including @var{split}. See @ref{Accounts} for details.
+ at end deftypefun
+
+ at deftypefun gnc_numeric xaccSplitGetShareReconciledBalance (Split * @code{split})
+Return the share reconciled balance of @var{split}'s parent Account up
+to and including @var{split}. See @ref{Accounts} for details.
+ at end deftypefun
+
+ at deftypefun {const char*} xaccSplitGetType (Split * @var{split})
+Return @var{split}'s type as a string. Currently, the possibilities are
+
+ @table @code
+ @item normal
+ a normal split -- the default.
+
+ @item stock-split
+ a split representing a stock split. The value should be 0 and the
+ share amount should represent the number of shares added/subtracted from
+ the account as a result of the forward/reverse stock split.
+ @end table
+
+ at end deftypefun
+
+
+ at node Split Setters, , Split Getters, Splits
+ at subsection Split Setters
+
+ at deftypefun void xaccSplitSetMemo (Split * @var{split}, const char * @var{memo})
+Set the memo field of @var{split} to @var{memo}.
+ at end deftypefun
+
+ at deftypefun void xaccSplitSetAction (Split * @var{split}, const char * @var{action})
+Set the action field of @var{split} to @var{memo}. The action field is
+an arbitrary string, but is intended to be conveniently limited to a
+menu of selections such as "Buy", "Sell", "Interest", etc.
+ at end deftypefun
+
+ at deftypefun void xaccSplitSetReconcile (Split * @var{split}, char @var{reconciled_flag})
+Set the reconciled flag of @var{split} to @var{reconciled_flag}. For the
+possible values and meanings of @var{reconciled_flag}, see @ref{Split Getters}.
+ at end deftypefun
+
+ at deftypefun void xaccSplitSetDateReconciledSecs (Split * @var{split}, time_t @var{time})
+Set the reconciliation date of @var{split} to @var{time}.
+ at end deftypefun
+
+ at deftypefun void xaccSplitSetDateReconciledTS (Split * @var{split}, Timespec * @var{ts})
+Set the reconciliation date of @var{split} to @var{ts}.
+ at end deftypefun
+
+ at deftypefun void xaccSplitSetShareAmount (Split * @var{split}, gnc_numeric amount)
+Set the share quantity of @var{split} to @var{amount}.
+ at end deftypefun
+
+ at deftypefun void xaccSplitSetSharePrice (Split * @var{split}, gnc_numeric @var{price})
+Set the share price of @var{split} to @var{price}.
+ at end deftypefun
+
+ at deftypefun void xaccSplitSetSharePriceAndAmount (Split * @var{split}, gnc_numeric @var{price}, gnc_numeric @var{amount})
+Set both the share price and share quantity of @var{split}. This routine
+is more efficent than calling @code{xaccSplitSetShareAmount} and
+ at code{xaccSplitSetSharePrice} in succesion.
+ at end deftypefun
+
+ at deftypefun void xaccSplitSetValue (Split * @var{split}, gnc_numeric @var{value})
+Adjust the share quantity of @var{split} so that @var{split}'s value is
+equal to @var{value}.
+ at end deftypefun
+
+ at deftypefun void xaccSplitSetBaseValue (Split * @var{split}, gnc_numeric @var{value}, const char * @var{base_currency})
+Set either the share quantity or value of @var{split} depending upon
+whether @var{base_currency} is the security or current of @var{split}'s
+parent Account. @xref{Accounts}.
+ at end deftypefun
+
+
+ at node Transactions, Accounts, Splits, Engine
+ at section Transactions
+ at tindex Transaction
+
+A Transaction is the Engine abstraction of an accounting entry in a
+Journal. In accounting terms, a Transaction is a Journal Entry. As
+such, it contains the following pieces of information:
+
+ at table @asis
+
+ at item A list of Ledger Entries, or Splits
+The list of debits and credits which make up this Transaction. As in
+accounting, a Transaction is balanced when the sum of the debits equals
+the sum of the credits.
+
+ at item The entry date
+The date the transaction was entered into GnuCash.
+
+ at item The post date
+The date the transaction was posted. This is often the date the
+transaction was recorded by the bank, or the date the user initiated
+the transaction (i.e., wrote the check, made the ATM withdrawal).
+
+ at item A transaction number field
+This field is intended to hold a transaction number, such as a
+check number or an ID assigned by a bank to an electronic transfer.
+
+ at item A description
+A textual description of the transaction.
+
+ at end table
+
+In addition to the above, Transactions contain a key-value pair frame.
+
+
+ at subsection The Transaction Edit Cycle
+
+The Engine supports (and, in fact, requires) a 2-phase commit/rollback
+cycle for modifying Transactions and their constituent Splits. A Transaction
+must be opened for editing using @code{xaccTransBeginEdit()} before any of
+the following actions may be taken.
+
+ at itemize
+
+ at item
+Modifying any field of a Transaction.
+
+ at item
+Modifying any Split belonging to the Transaction. That includes
+re-parenting a Split to a different Account or a different Transaction.
+In the case of re-parenting to a new Transaction, both Transactions must
+be opened for editing.
+
+ at item
+Deleting any Split belonging to the Transaction.
+
+ at item
+Adding a Split to the transaction.
+
+ at item
+Deleting the Transaction.
+
+ at end itemize
+
+After the desired changes have been made, they must either be committed
+using @code{xaccTransCommitEdit()} or rolled back using
+ at code{xaccTransRollbackEdit()}. Rolling back a transaction will undo any
+changes which have been made to it or to its Splits since it was opened
+for editing.
+
+
+ at menu
+* General Transaction API::
+* Transaction Getters::
+* Transaction Setters::
+ at end menu
+
+
+ at node General Transaction API, Transaction Getters, Transactions, Transactions
+ at subsection General Transaction API
+
+ at deftypefun {Transaction *} xaccMallocTransaction (void)
+Allocate, initialize, and return a new Transaction.
+ at end deftypefun
+
+ at deftypefun void xaccTransDestroy (Transaction * {trans})
+Remove all of the Splits from each of their accounts and free the memory
+associated with them. This routine must be followed by either an
+ at code{xaccTransCommitEdit()} in which case the transaction memory will
+be freed, or by @code{xaccTransRollbackEdit()}, in which case all the
+original Splits are put back into place.
+ at end deftypefun
+
+ at deftypefun void xaccTransAppendSplit (Transaction * @var{trans}, Split * @var{split})
+Append @var{split} to the collection of Splits in @var{trans}. If the
+Split is already a part of another Transaction, it will be removed from
+that Transaction first.
+ at end deftypefun
+
+ at deftypefun void xaccTransBeginEdit (Transaction * @var{trans})
+This method must be called before any changes are made to @var{trans} or
+any of its component Splits. If this is not done, errors will result.
+ at end deftypefun
+
+ at deftypefun void xaccTransCommitEdit (Transaction * @var{trans})
+This method indicates that the changes to @var{trans} and its Splits are
+complete and should be made permanent. Note this routine may result in
+the deletion of the transaction, if the Transaction is "empty" (has no
+Splits) or if @code{xaccTransDestroy()} was called on the Transaction.
+ at end deftypefun
+
+ at deftypefun void xaccTransRollbackEdit (Transaction * @var{trans})
+Rejects all changes made to @var{trans} and its Splits, and sets
+ at var{trans} back to where it was before the @code{xaccTransBeginEdit()}
+call. This includes restoring any deleted Splits, removing any added
+Splits, and undoing the effects of @code{xaccTransDestroy()}, as well
+as restoring share quantities, memos, descriptions, etc.
+ at end deftypefun
+
+ at deftypefun gboolean xaccTransIsOpen (Transaction * @var{trans})
+Return @code{TRUE} if @var{trans} is open for editing. Otherwise, it
+returns @code{FALSE}.
+ at end deftypefun
+
+ at deftypefun {const GUID *} xaccTransGetGUID (Transaction * @var{trans})
+Return the GUID of @var{trans}.
+ at end deftypefun
+
+ at deftypefun {Transaction *} xaccTransLookup (const GUID * @var{guid})
+Return the Transaction associated with @var{GUID}, or @code{NULL} if
+there is no such Transaction.
+ at end deftypefun
+
+ at deftypefun {kvp_value *} xaccTransGetSlot (Transaction * @var{trans}, const char * @var{key})
+Return the @code{kvp_value} associated with @var{key} in @var{trans}.
+If there is none, @code{NULL} is returned.
+ at end deftypefun
+
+ at deftypefun void xaccTransSetSlot (Split * @var{trans}, const char * @var{key}, const kvp_value * @var{value})
+Associate a copy of @var{value} with @var{key} in @var{trans}.
+ at end deftypefun
+
+
+ at node Transaction Getters, Transaction Setters, General Transaction API, Transactions
+ at subsection Transaction Getters
+
+ at deftypefun {Split *} xaccTransGetSplit (Transaction * @var{trans}, int @var{i})
+Return the @var{I}th Split of @var{trans}.
+ at end deftypefun
+
+ at deftypefun {GList *} xaccTransGetSplitList (Transaction * @var{trans})
+Return a @code{GList} of the Splits in @var{trans}. This list is owned
+by @var{trans} and should not be modified in any way!
+ at end deftypefun
+
+ at deftypefun {const char *} xaccTransGetNum (Transaction * @var{trans})
+Return the number field of @var{trans}.
+ at end deftypefun
+
+ at deftypefun {const char *} xaccTransGetDescription (Transaction * @var{trans})
+Return the description field of @var{trans}.
+ at end deftypefun
+
+ at deftypefun time_t xaccTransGetDate (Transaction * @var{trans})
+Return the post date of @var{trans} as a @code{time_t} value.
+ at end deftypefun
+
+ at deftypefun {long long} xaccTransGetDateL (Transaction * @var{trans})
+Return the post date of @var{trans} as a @code{long long} value.
+ at end deftypefun
+
+ at deftypefun void xaccTransGetDateTS (Transaction * @var{trans}, Timespec * @var{ts})
+Return the post date of @var{trans} in @var{ts}.
+ at end deftypefun
+
+ at deftypefun void xaccTransGetDateEnteredTS (Transaction * @var{trans}, Timespec * @var{ts})
+Return the entry date of @var{trans} in @var{ts}.
+ at end deftypefun
+
+ at deftypefun {char *} xaccTransGetDateStr (Transaction * @var{trans})
+Return a string representing the post date of @var{trans}, or NULL if
+ at var{trans} is NULL. The string must be freed with @code{free()} after
+use.
+ at end deftypefun
+
+ at deftypefun int xaccTransCountSplits (Transaction * @var{trans})
+Return the number of Splits in @var{trans}.
+ at end deftypefun
+
+
+ at node Transaction Setters, , Transaction Getters, Transactions
+ at subsection Transaction Setters
+
+Remember, before you modify a Transaction, you must open it for editing
+with @code{xaccTransBeginEdit}.
+
+ at deftypefun void xaccTransSetDate (Transaction * @var{trans}, int @var{day}, int @var{mon}, int @var{year})
+Set the post date of @var{trans} with @var{day}, @var{month}, and @var{year}.
+ at end deftypefun
+
+ at deftypefun void xaccTransSetDateSecs (Transaction * @var{trans}, time_t @var{time})
+Set the post date of @var{trans} using a @code{time_t} value.
+ at end deftypefun
+
+ at deftypefun void xaccTransSetDateToday (Transaction * @var{trans})
+Set the post date of @var{trans} to the current time.
+ at end deftypefun
+
+ at deftypefun void xaccTransSetDateTS (Transaction * @var{trans}, const Timespec * @var{ts})
+Set the post date of @var{trans} from @var{ts}.
+ at end deftypefun
+
+ at deftypefun void xaccTransSetDateEnteredSecs (Transaction *trans, time_t time)
+Set the entry date of @var{trans} from a @code{time_t} value.
+ at end deftypefun
+
+ at deftypefun void xaccTransSetDateEnteredTS (Transaction * @var{trans}, const Timespec * @var{ts})
+Set the entry date of @var{trans} from @var{ts}.
+ at end deftypefun
+
+ at deftypefun void xaccTransSetNum (Transaction * @var{trans}, const char * @var{num})
+Set the number field of @var{trans} to @var{num}.
+ at end deftypefun
+
+ at deftypefun void xaccTransSetDescription (Transaction * @var{trans}, const char * @var{desc})
+Set the description field of @var{trans} to @var{desc}.
+ at end deftypefun
+
+
+ at node Accounts, Account Groups, Transactions, Engine
+ at section Accounts
+ at tindex Account
+
+An Account is the Engine abstraction of an, well, an account. Accounts
+contain the following pieces of information:
+
+ at table @asis
+
+ at item A list of Ledger Entries, or Splits
+The list of debits and credits which apply to the Account. The sum of
+all debits and credits is the account balance.
+
+ at item A type
+An integer code identifying the type of account. The Account type
+determines whether the Account holds shares valued in a currency
+or not. It is also used by the GUI and reporting system to determine
+how debits & credits to the Account should be treated and displayed.
+
+ at item A name
+The name of the Account.
+
+ at item An account code
+A string that is intended to hold a unique user-selected identifier
+for the account. However, uniqueness of this field is not enforced.
+
+ at item A description
+A textual description of the Account.
+
+ at item A currency
+The commodity that Splits in the account are valued in, i.e., the
+denomination of the 'value' member of Splits in the account.
+
+ at item A curreny SCU
+The SCU is the smallest convertible unit that the currency is
+traded in. This value overrides the default SCU of the currency.
+
+ at item A security
+For Accounts which may contain shares (such as stock accounts),
+the denomination of the 'share quantity' member of Splits in
+the accounts. For accounts which do not contain shares, the
+security is blank, and the share quantities are denominated
+in the Account currency.
+
+ at item A security SCU
+Analogous to the currency SCU, but for the security.
+
+ at item A parent and child Account Group.
+The parent and child of an Account are Account Groups
+(@pxref{Account Groups}). Account Groups are used to
+connect Accounts together into an Account hierarchy.
+If the parent Account Group is not present, the Account
+is at the top level of the hierarchy. If the child
+Account Group is not present, the Account has no
+children.
+
+ at end table
+
+In addition to the above, Accounts contain a key-value pair frame.
+
+ at menu
+* Account Types::
+* General Account API::
+* Account Type API::
+* Account Getters::
+* Account Tax API::
+ at end menu
+
+
+ at node Account Types, General Account API, Accounts, Accounts
+ at subsection Account Types
+ at tindex GNCAccountType
+
+Account Types are defined by the @code{GNCAccountType} enumeration.
+Possible values are:
+
+ @table @code
+
+ @item BAD_TYPE, NO_TYPE
+ Both of these values indicate an illegal Account type.
+
+ @item BANK
+ Denotes a savings or checking account held at a bank.
+ Such an account is often interest bearing.
+
+ @item CASH
+ Denotes a shoe-box or pillowcase stuffed with cash. In other
+ words, actual currency held by the user.
+
+ @item CREDIT
+ Denotes credit card accounts.
+
+ @item ASSET
+ Denotes a generic asset account.
+
+ @item LIABILITY
+ Denotes a generic liability account.
+
+ @item STOCK
+ A stock account containing stock shares.
+
+ @item MUTUAL
+ A mutual fund account containing fund shares.
+
+ @item CURRENCY
+ Denotes a currency trading account. In many ways, a currency trading
+ account is like a stock trading account, where both quantities
+ and prices are set. However, generally both currency and security
+ are national currencies.
+
+ @item INCOME
+ Denotes an income account. The GnuCash financial model does not
+ use 'categories'. Actual accounts are used instead.
+
+ @item EXPENSE
+ Denotes an expense account.
+
+ @item EQUITY = 10,
+ Denotes an equity account.
+
+ @end table
+
+
+ at node General Account API, Account Type API, Account Types, Accounts
+ at subsection General Account API
+
+ at deftypefun {Account *} xaccMallocAccount (void)
+Allocate and initialize an Account. The account must be
+destroyed by calling @code{xaccAccountBeginEdit} followed
+by @code{xaccAccountDestroy}.
+ at end deftypefun
+
+ at deftypefun void xaccAccountDestroy (Account * @var{account})
+Destroys @var{account} and frees all memory associated with
+it. This routine will also destroy the Account's children.
+You must call @code{xaccAccountBeginEdit} before calling
+this function.
+ at end deftypefun
+
+ at deftypefun void xaccAccountBeginEdit (Account * @var{account})
+This routine, together with @code{xaccAccountCommitEdit},
+provide a two-phase-commit wrapper for account updates
+much in the same way as @var{xaccTransBeginEdit} and
+ at var{xaccTransCommitEdit} do for Transactions.
+ at end deftypefun
+
+ at deftypefun void xaccAccountCommitEdit (Account * @var{account})
+The counterpart to @var{xaccAccountBeginEdit}.
+ at end deftypefun
+
+ at deftypefun {Account *} xaccCloneAccountSimple (const Account * @var{from})
+Return a 'copy' of @var{from} that is identical in the type, name, code,
+description, kvp data, and currency. All other fields are the same as an
+account returned by @code{xaccMallocAccount}.
+ at end deftypefun
+
+ at deftypefun {const GUID *} xaccAccountGetGUID (Account * @var{account})
+Return the globally unique id associated with @var{account}.
+ at end deftypefun
+
+ at deftypefun {Account *} xaccAccountLookup (const GUID * @var{guid})
+Return the Account associated with @var{guid}, or NULL if there is
+no such Account.
+ at end deftypefun
+
+ at deftypefun {kvp_frame *} xaccAccountGetSlots (Account * @var{account})
+Return the @code{kvp_frame} associated with @var{account}. User code
+may modify this @code{kvp_frame}, but must not destroy it.
+ at end deftypefun
+
+ at deftypefun void xaccAccountSetSlots_nc (Account * @var{account}, kvp_frame * @var{frame})
+Set the @code{kvp_frame} associated wih @var{account}. After the call,
+ at var{frame} is owned by @var{account}, so don't destroy it.
+ at end deftypefun
+
+
+ at node Account Type API, Account Getters, General Account API, Accounts
+ at subsection Account Type API
+
+ at deftypefun {const char *} xaccAccountGetTypeStr (GNCAccountType @var{type})
+Return a string corresponding to the given Account type suitable for
+display by a GUI. The string is translated with gettext according to
+the current locale.
+ at end deftypefun
+
+ at deftypefun {char *} xaccAccountTypeEnumAsString (GNCAccountType @var{type})
+Return a string corresponding to the given Account type. The string
+is not translated and is independent of the current locale.
+ at end deftypefun
+
+ at deftypefun gboolean xaccAccountStringToType (const char * @var{str}, GNCAccountType * @var{type})
+Converts a string of the form returned by @code{xaccAccountTypeEnumAsString}
+to a type, return in @var{type}. Returns true if the string corresponds
+to an actual type.
+ at end deftypefun
+
+ at deftypefun GNCAccountType xaccAccountStringToEnum (const char * @var{str})
+Similar to @code{xaccAccountStringToEnum}, but returns the type. If
+ at var{str} does not correspond to any valid type, @code{BAD_TYPE} is
+returned.
+ at end deftypefun
+
+ at deftypefun gboolean xaccAccountTypesCompatible (GNCAccountType @var{parent_type}, GNCAccountType @var{child_type})
+Returns TRUE if accounts of type @var{parent_type} can have child accounts
+of type @var{child_type}. This compatibility is not enforced by the
+engine, but one day it may be!
+ at end deftypefun
+
+
+ at node Account Getters, Account Tax API, Account Type API, Accounts
+ at subsection Account Getters
+
+ at deftypefun GNCAccountType xaccAccountGetType (Account * @var{account})
+Return the type of @var{account}.
+ at end deftypefun
+
+ at deftypefun {const char *} xaccAccountGetName (Account * @var{account})
+Return the name of @var{account}.
+ at end deftypefun
+
+ at deftypefun {const char *} xaccAccountGetCode (Account * @var{account})
+Return the code of @var{account}.
+ at end deftypefun
+
+ at deftypefun {const char *} xaccAccountGetDescription (Account * @var{account})
+Return the description of @var{account}.
+ at end deftypefun
+
+ at deftypefun {const char *} xaccAccountGetNotes (Account * @var{account})
+Return the notes of @var{account}.
+ at end deftypefun
+
+ at deftypefun {gnc_commodity *} xaccAccountGetCurrency (Account * @var{account})
+Return the currency of @var{account}.
+ at end deftypefun
+
+ at deftypefun int xaccAccountGetCurrencySCU (Account * @var{account})
+Return the SCU (smallest convertible unit) of @var{account}'s
+currency.
+ at end deftypefun
+
+ at deftypefun {gnc_commodity *} xaccAccountGetSecurity (Account * @var{account})
+Return the security of @var{account}. For accounts without shares, this
+field will be @code{NULL}.
+ at end deftypefun
+
+ at deftypefun int xaccAccountGetSecuritySCU (Account * @var{account})
+Return the SCU (smallest convertible unit) of @var{account}'s
+security.
+ at end deftypefun
+
+ at deftypefun {gnc_commodity *} xaccAccountGetEffectiveSecurity (Account * @var{account})
+Get the `effective' security of the account. If the account has a non-NULL
+security field, that field will be returned. Otherwise, the currency will
+be returned.
+ at end deftypefun
+
+ at deftypefun {AccountGroup *} xaccAccountGetChildren (Account * @var{account})
+Return the child group of @var{account}. The child group may be @code{NULL},
+indicating @var{account} has no children.
+ at end deftypefun
+
+ at deftypefun {AccountGroup *} xaccAccountGetParent (Account * @var{account})
+Return the parent Group of @var{account}. The parent may be @code{NULL},
+indicating @var{account} is a top-level Account. However, even if the
+parent is not @code{NULL}, the account may still be top-level if the
+parent Group has no parent Account.
+ at end deftypefun
+
+ at deftypefun {Account *} xaccAccountGetParentAccount (Account * @var{account})
+Similar to @code{xaccAccountGetParent}, but returns the parent Account
+of the parent Group if the parent Group exists. Otherwise, returns
+ at code{NULL}.
+ at end deftypefun
+
+ at deftypefun gnc_numeric xaccAccountGetBalance (Account * @var{account})
+Return the balance of @var{account}, which is also the balance of the
+last Split in @var{account}. If there are no Splits, the balance is
+zero. The balance is denominated in the Account currency.
+ at end deftypefun
+
+ at deftypefun gnc_numeric xaccAccountGetClearedBalance (Account * @var{account})
+Return the cleared balance of @var{account}. The cleared balance is the
+balance of all Splits in @var{account} which are either cleared or
+reconciled or frozen. The cleared balance is denominated in the Account
+currency.
+ at end deftypefun
+
+ at deftypefun gnc_numeric xaccAccountGetReconciledBalance (Account * @var{account})
+Return the reconciled balance of @var{account}. The reconciled balance
+is the balance of all Splits in @var{account} which are reconciled or
+frozen. The reconciled balance is denominated in the Account currency.
+ at end deftypefun
+
+ at deftypefun gnc_numeric xaccAccountGetShareBalance (Account *account)
+Return the share balance of @var{account}, which is also the share
+balance of the last Split in @var{account}. If there are no Splits, the
+balance is zero. The balance is denominated in the Account security, if
+the Account security exits; otherwise the share balance is denominated
+in the Account currency.
+ at end deftypefun
+
+ at deftypefun gnc_numeric xaccAccountGetShareClearedBalance (Account * @var{account})
+Return the cleared share balance of @var{account}. The cleared share
+balance is the share balance of all Splits in @var{account} which are
+either cleared or reconciled or frozen. The cleared share balance is
+denominated as the share balance.
+ at end deftypefun
+
+ at deftypefun gnc_numeric xaccAccountGetShareReconciledBalance (Account * @var{account})
+Return the reconciled share balance of @var{account}. The reconciled
+share balance is the share balance of all Splits in @var{account} which
+are reconciled or frozen. The reconciled sharea balance is denominated
+as the share balance.
+ at end deftypefun
+
+ at deftypefun gnc_numeric xaccAccountGetBalanceAsOfDate (Account * @var{account}, time_t @var{date})
+Return the balance of @var{account} including all Splits whose parent
+Transactions have posted dates on or before @var{date}.
+ at end deftypefun
+
+ at deftypefun gnc_numeric xaccAccountGetShareBalanceAsOfDate (Account * @var{account}, time_t @var{date})
+Return the share balance of @var{account} including all Splits whose
+parent Transactions have posted dates on or before @var{date}.
+ at end deftypefun
+
+ at deftypefun {GList *} xaccAccountGetSplitList (Account * @var{account})
+Return a @code{GList} of the Splits in @var{account}. This list must
+not be modified in any way.
+ at end deftypefun
+
+ at deftypefun {char *} xaccAccountGetFullName (Account * @var{account}, const char @var{separator})
+Returns the fully qualified name of @var{account} using the given
+separator character. The name must be g_freed after use. The fully
+qualified name of an account is the concatenation of the names of the
+account and all its ancestor accounts starting with the topmost account
+and ending with the given account. Each name is separated by the given
+character.
+ at end deftypefun
+
+
+ at node Account Tax API, , Account Getters, Accounts
+ at subsection Account Tax API
+
+This set of API calls is related to tax information. All accounts have a
+tax-related boolean flag that can be set or unset. There is an
+additional set of API calls related to United States taxes that have
+`US' in the function call names. Future API calls that are specific to
+other countries should include the appropriate 2-letter country code in
+the function names.
+
+ at deftypefun gboolean xaccAccountGetTaxRelated (Account * @var{account})
+Return the tax-related flag of @var{account}.
+ at end deftypefun
+
+ at deftypefun void xaccAccountSetTaxRelated (Account * @var{account}, gboolean @var{tax_related})
+Set the tax-related flag of @var{account}.
+ at end deftypefun
+
+ at deftypefun {const char *} xaccAccountGetTaxUSCode (Account * @var{account})
+Get the US-specific tax code associated with @var{account}, or
+ at code{NULL} if there is none. These codes are internal to GnuCash
+and currently defined in @file{src/scm/report/txf-export.scm}.
+ at end deftypefun
+
+ at deftypefun void xaccAccountSetTaxUSCode (Account * @var{account}, const char * @var{code})
+Set the US-specific tax code associated with @var{account}.
+ at end deftypefun
+
+ at deftypefun {const char *} xaccAccountGetTaxUSPayerNameSource (Account * @var{account})
+Get the payer name source associated with @var{account}. See
+ at file{src/scm/repot/taxtxf.scm} for details.
+ at end deftypefun
+
+ at deftypefun void xaccAccountSetTaxUSPayerNameSource (Account * @var{account}, const char * @var{source})
+Set the payer name source associated with @var{account}.
+ at end deftypefun
+
+
+ at node Account Groups, GNCBooks, Accounts, Engine
+ at section Account Groups
+ at tindex AccountGroup
+
+Account Groups are used by the Engine to connect Accounts
+together into an Account hierarchy. Account Groups do not
+correspond to any accounting concept -- they are specific
+to the GnuCash engine. Account Groups contain the following
+pieces of information:
+
+ at table @asis
+
+ at item A list of Accounts
+The list Accounts in the Group.
+
+ at item A not-saved flag
+Indicates whether any information in the hierarchy
+rooted at the Group needs to be saved. That includes
+Accounts, Splits, and Transactions.
+
+ at end table
+
+Account Groups do not have key-value frames or GUIDs.
+
+ at menu
+* General Account Group API::
+* Account Group Account API::
+ at end menu
+
+ at node General Account Group API, Account Group Account API, Account Groups, Account Groups
+ at subsection General Account Group API
+
+ at deftypefun {AccountGroup *} xaccMallocAccountGroup (void)
+Return a newly-allocated & initialized Account Group.
+The Group must be freed with @code{xaccFreeAccountGroup}.
+ at end deftypefun
+
+ at deftypefun void xaccFreeAccountGroup (AccountGroup * @var{account_group})
+Free the given Group and all its resources, including the Accounts.
+ at end deftypefun
+
+ at deftypefun void xaccAccountGroupCommitEdit (AccountGroup * @var{grp})
+Recursively call @code{xaccAccountCommitEdit} on all child accounts
+and their children.
+ at end deftypefun
+
+ at deftypefun void xaccGroupConcatGroup (AccountGroup * @var{to}, AccountGroup * @var{from})
+Move all accounts in @var{from} to @var{to}. After this function
+returns, @var{from} will have been destroyed.
+ at end deftypefun
+
+ at deftypefun void xaccGroupMergeAccounts (AccountGroup * @var{grp})
+Merge all accounts in @var{grp} that have the same name and description.
+The semantics of this function are rather complex. Consult the
+implementation before use!
+ at end deftypefun
+
+ at deftypefun gboolean xaccGroupNotSaved (AccountGroup * @var{grp})
+Return true if @var{grp} has changes which have not been saved.
+ at end deftypefun
+
+ at deftypefun void xaccGroupMarkSaved (AccountGroup * @var{grp})
+Mark @var{grp} and all its children as saved.
+ at end deftypefun
+
+ at deftypefun void xaccGroupMarkNotSaved (AccountGroup * @var{grp})
+Mark @var{grp} as not saved.
+ at end deftypefun
+
+ at deftypefun void xaccGroupMarkDoFree (AccountGroup * @var{grp})
+Mark all accounts in @var{grp} as slated for destruction. This will
+improve the efficiency of destroying a large account hierarchy.
+ at end deftypefun
+
+
+ at node Account Group Account API, , General Account Group API, Account Groups
+ at subsection Account Group Account API
+
+ at deftypefun void xaccGroupRemoveAccount (AccountGroup * @var{grp}, Account * @var{account})
+Remove @var{account} from @var{grp}. If @var{account} is not in
+ at var{grp}, the function will return without performing any action.
+In no case will @var{account} be destroyed or modified.
+ at end deftypefun
+
+ at deftypefun void xaccAccountRemoveGroup (Account * @var{acc})
+Remove @var{acc}'s child group. The child group is not otherwise
+modified or destroyed.
+ at end deftypefun
+
+ at deftypefun void xaccGroupInsertAccount (AccountGroup * @var{grp}, Account * @var{acc})
+Add @var{acc} to @var{grp}. If @var{acc} is in another Group, it will be
+removed first.
+ at end deftypefun
+
+ at deftypefun void xaccAccountInsertSubAccount (Account * @var{parent}, Account * @var{child})
+Like @code{xaccGroupInsertAccount}, but uses a parent Account instead
+of a parent group. If @var{parent} does not have a child Group, one
+will be created.
+ at end deftypefun
+
+ at deftypefun int xaccGroupGetNumSubAccounts (AccountGroup * @var{grp})
+Return the total number of Accounts in the hierarchy rooted at @var{grp}.
+ at end deftypefun
+
+ at deftypefun int xaccGroupGetNumAccounts (AccountGroup * @var{grp})
+Return the number of accounts in @var{grp}. This count does not
+include Accounts lower in the hierarchy.
+ at end deftypefun
+
+ at deftypefun int xaccGroupGetDepth (AccountGroup * @var{grp})
+Returns the length of the longest tree branch in the hierarchy
+rooted at @var{grp}. Each link between an Account and its
+(non-null) children counts as one unit of length.
+ at end deftypefun
+
+ at deftypefun {Account *} xaccGroupGetAccount (AccountGroup * @var{group}, int @var{index})
+Return the @var{index}th Account in @var{group}, starting at zero.
+If @var{index} is out of range, @code{NULL} is returned.
+ at end deftypefun
+
+ at deftypefun {GList *} xaccGroupGetSubAccounts (AccountGroup * @var{grp})
+Return a list of the Accounts, including sub-Accounts, in @var{grp}. The
+returned list should be freed with @code{g_list_free} when no longer
+needed.
+ at end deftypefun
+
+ at deftypefun {GList *} xaccGroupGetAccountList (AccountGroup * @var{grp})
+Return a list of the immediate children of @var{grp}. The returned list
+should not be freed or modified in any way.
+ at end deftypefun
+
+
+ at node GNCBooks, Scrub, Account Groups, Engine
+ at section GNCBooks
+ at tindex GNCBook
+
+The @dfn{GNCBook} interface encapsulates all the information about a
+GnuCash dataset, including the methods used to read and write the
+dataset to datastores. This class provides several important services:
+
+ at itemize
+
+ at item
+Prevents multiple users from editing the same file at the same time,
+thus avoiding lost data due to race conditions. Thus an 'open book'
+implies that the associated file is locked.
+
+ at item
+Provides a search path for the file to be edited. This should simplify
+install & maintenance problems for users who may not have a good grasp
+of what a file system is, or where they want to keep their data files.
+
+ at end itemize
+
+The current implementation assumes the use of files and file locks;
+however, the API was designed to be general enough to allow the use
+of generic URL's, and/or implementation on top of SQL or other
+database/persistant object technology.
+
+ at menu
+* GNCBook API::
+ at end menu
+
+
+ at node GNCBook API, , GNCBooks, GNCBooks
+ at subsection GNCBook API
+
+ at deftypefun {GNCBook *} gnc_book_new (void)
+Allocate, initialize, and return a new GNCBook. The new book will contain
+a newly allocated AccountGroup.
+ at end deftypefun
+
+ at deftypefun void gnc_book_destroy (GNCBook * @var{book})
+End any editing session associated with @var{book}, and free all
+memory associated with it.
+ at end deftypefun
+
+ at deftypefun gboolean gnc_book_begin (GNCBook * @var{book}, const char * @var{book_id}, gboolean ignore_lock, gboolean create_if_nonexistent)
+Begins a new book editing sesssion. It takes as an argument the book id.
+The book id must be a string in the form of a URI/URL. In the current
+implementation, only one type of URI is supported, and that is the file
+URI: anything of the form @url{file:/home/somewhere/somedir/file.xac}
+The path part must be a valid path. The file-part must be a valid
+GnuCash data file. Paths may be relative or absolute. If the path is
+relative; that is, if the argument is @url{file:somefile.xac} then a
+sequence of search paths are checked for a file of this name.
+
+The 'ignore_lock' argument, if set to TRUE, will cause this routine to
+ignore any file locks that it finds. If set to FALSE, then file locks
+will be tested and obeyed.
+
+If the file exists, can be opened and read, and a lock can be obtained
+then a lock will be obtained and the function returns TRUE.
+
+If the file/database doesn't exist, and the create_if_nonexistent flag
+is set to TRUE, then the database is created.
+
+Otherwise the function returns FALSE.
+ at end deftypefun
+
+ at deftypefun gboolean gnc_book_load (GNCBook * @var{book})
+Load the data associated with the book. The function returns TRUE on
+success.
+ at end deftypefun
+
+ at deftypefun GNCBackendError gnc_book_get_error (GNCBook * @var{book})
+Obtain the reason for a failure. Standard errno values are used. Calling
+this routine resets the error value. This routine allows an
+implementation of multiple error values, e.g. in a stack, where this
+routine pops the top value. The current implementation has a stack that
+is one-deep.
+
+Some important error values:
+
+ at table @code
+
+ at item EINVAL
+bad argument
+
+ at item ETXTBSY
+book id is in use; it's locked by someone else
+
+ at item ENOSYS
+unsupported URI type
+
+ at item ERANGE
+file path too long
+
+ at item ENOLCK
+book not open when @code{gnc_book_save()} was called.
+
+ at end table
+ at end deftypefun
+
+ at deftypefun {const char *} gnc_book_get_error_message (GNCBook * @var{book})
+Return a string describing the reason for the current error. Calling
+this routine resets the error value.
+ at end deftypefun
+
+ at deftypefun GNCBackendError gnc_book_pop_error (GNCBook * @var{book})
+Same as @code{gnc_book_get_error}, but the error value is reset
+in @var{book}.
+ at end deftypefun
+
+ at deftypefun {AccountGroup *} gnc_book_get_group (GNCBook * @var{book})
+Return the current top-level account group.
+ at end deftypefun
+
+ at deftypefun void gnc_book_set_group (GNCBook * @var{book}, AccountGroup * @var{topgroup})
+Set the topgroup to a new value.
+ at end deftypefun
+
+ at deftypefun {const char *} gnc_book_get_file_path (GNCBook * @var{book})
+Return the fully-qualified file path for the book. That is, if a
+relative or partial filename was for the book, then it had to have been
+fully resolved to open the book. This routine returns the result of this
+resolution.
+ at end deftypefun
+
+ at deftypefun gboolean gnc_book_save_may_clobber_data (GNCBook * @var{book})
+Return TRUE if saving the book would overwrite other information.
+ at end deftypefun
+
+ at deftypefun void gnc_book_save (GNCBook * @var{book})
+Commit all changes that have been made to the book.
+ at end deftypefun
+
+ at deftypefun void gnc_book_end (GNCBook * @var{book})
+Release the session lock. It will @emph{not} save the account group to
+a file. Thus, this method acts as an "abort" or "rollback" primitive.
+ at end deftypefun
+
+
+ at node Scrub, , GNCBooks, Engine
+ at section Scrub
Deleted: gnucash/trunk/src/doc/design/engine.texinfo
===================================================================
--- gnucash/trunk/src/doc/design/engine.texinfo 2013-10-27 21:57:42 UTC (rev 23343)
+++ gnucash/trunk/src/doc/design/engine.texinfo 2013-10-28 01:02:53 UTC (rev 23344)
@@ -1,2842 +0,0 @@
- at node Engine, Component Manager, Top Level, Top
- at chapter Engine
- at cindex The Engine
-
- at strong{This whole document is completely outdated. Don't read this. All
-function names and every described structure has changed
-completely. Only read this if you want to know how gnucash looked like
-in 1999. This is completely outdated!}
-
-The Engine provides an interface to a financial engine with three basic
-financial entities: Accounts, Transactions (known as Journal Entries in
-accounting practice), and Splits (known as Ledger Entries). These three
-entities are the central data structures of the GnuCash financial data
-model.
-
-In addition, the Engine provides the abstraction of Account Groups
-(collections of related accounts) and GNCBooks. A GNCBook abstracts both
-a set of related GnuCash data (financial entities plus additional
-information such as budgets, per-file preferences, etc.) plus a
-file-editing session allowing transparent support for locking and
-implementation with other backends such as SQL.
-
-The Engine code contains no GUI code whatsoever and is designed to
-be created as a shared library for use by other programs.
-
- at menu
-* Engine Introduction::
-* Using and Extending the Engine API::
-* Globally Unique Identifiers::
-* Numeric Library::
-* Key-Value Pair Frames::
-* Events::
-* Commodities::
-* Commodity Tables::
-* Prices::
-* Price Databases::
-* Splits::
-* Transactions::
-* Accounts::
-* Account Groups::
-* GNCBooks::
-* Scrub::
- at end menu
-
-
- at node Engine Introduction, Using and Extending the Engine API, Engine, Engine
- at section Introduction
-
-Splits (@pxref{Splits}), or "Ledger Entries" are the fundamental
-accounting units. Each Split consists of an amount (number of dollar
-bills, number of shares, etc.), the value of that amount expressed in
-a (possibly) different currency than the amount, a Memo, a pointer to
-the parent Transaction, a pointer to the debited Account, a reconciled
-flag and timestamp, an "Action" field, and a key-value frame which can
-store arbitrary data (@pxref{Key-Value Pair Frames}).
-
-Transactions (@pxref{Transactions}) embody the notion of "double entry"
-accounting. A Transaction consists of a date, a description, an ID number, a
-list of one or more Splits, and a key-value frame. The transaction
-also specifies the currency with which all of the splits will be
-valued. When double-entry rules are enforced, the total value of
-the splits are zero. If there are only two splits,
-then the value of one must be positive, the other negative: this denotes
-that one account is debited, and another is credited by an equal
-amount. By forcing the value of the splits to always 'add up' to
-zero, we can gaurentee that the balances of the accounts are always
-correctly balanced.
-
-The engine does not enforce double-entry accounting, but provides an API
-to enable user-code to find unbalanced transactions and 'repair' them so
-that they are in balance. @xref{Scrub}.
-
-Note the sum of the values of Splits in a Transaction is always computed
-with respect to a currency; thus splits can be balanced even when they
-are in different currencies, as long as they share a common currency.
-This feature allows currency-trading accounts to be established.
-
-Every Split must point to its parent Transaction, and that Transaction
-must in turn include that Split in the Transaction's list of Splits. A
-Split can belong to at most one Transaction. These relationships are
-enforced by the engine. The engine user cannnot accidentally destroy
-this relationship as long as they stick to using the API and never
-access internal structures directly.
-
-Splits are grouped into Accounts (@pxref{Accounts}) which are also known
-as "Ledgers" in accounting practice. Each Account consists of a list of
-Splits that debit that Account. To ensure consistency, if a Split points
-to an Account, then the Account must point to the Split, and vice-versa.
-A Split can belong to at most one Account. Besides merely containing a
-list of Splits, the Account structure also give the Account a name, a
-code number, description and notes fields, a key-value frame, a pointer
-to the commodity that is used for all splits in this account. The
-commodity can be the name of anything traded and tradable: a stock
-(e.g. "IBM", "McDonald's"), a currency (e.g. "USD", "GBP"), or
-anything added to the commodity table.
-
-Accounts can be arranged in a hierarchical tree. The nodes of the tree
-are called "Account Groups" (@pxref{Account Groups}). By accounting
-convention, the value of an Account is equal to the value of all of its
-Splits plus the value of all of its sub-Accounts.
-
-
- at node Using and Extending the Engine API, Globally Unique Identifiers, Engine Introduction, Engine
- at section Using and Extending the Engine API
-
-Engine API calls are named using a specific convention. For example,
-the function to access the Memo field of a Split is
- at code{xaccSplitGetMemo}. The prefix @code{xacc} comes
-first at footnote{The @code{xacc} prefix is a historical artifact. GnuCash
-was derived from X-Accountant by Robin Clark.}, followed by the name of
-the entity for which the API call applies (@code{Split}), followed by
-the action performed by the call (@code{Get}), followed by the name of
-the field being accessed (@code{Memo}). Future API calls should conform
-to this naming convention.
-
-The formal arguments to Engine API calls always begin with the entity to
-which the call applies. Thus, the arguments to @code{xaccSplitSetMemo}
-are the @code{Split} pointer followed by the pointer to a memo
-string. Future API calls should also conform to this convention.
-
-Engine API calls should be implemented to behave as gracefully as
-possible with unexpected input. Specifically, public API calls should
-gracefully handle @code{NULL} pointer arguments. User code should be
-able to handle @code{NULL} return values from Engine calls as well.
-
-
- at node Globally Unique Identifiers, Numeric Library, Using and Extending the Engine API, Engine
- at section Globally Unique Identifiers
- at cindex Globally Unique Identifier
- at tindex GUID
-
-It is common for Engine structures to reference other Engine structures.
-For example, an Account must reference its Splits, its parent Account
-Group, and its child Account Group. Furthermore, other GnuCash modules
-may need to reference Engine structures. For example, a GUI
-implementation may wish to save a list of Accounts which the user has
-open when the application exits in order to restore that same state upon
-the next invocation.
-
-One way to uniquely identify an Engine structure, at least while the
-program is running, is using the C pointer which points to the
-structure. C pointers have the advantage of speed, but also have some
-disadvantages:
-
- at itemize
-
- at item
-Pointers cannot be used in data files and are not persistant across
-different program invocations.
-
- at item
-When an entity is destroyed, every other structure which references that
-entity through a direct pointer must be immediately updated to prevent
-illegal accesses.
-
- at end itemize
-
-The @dfn{GUID} (Globally Unique Identifier) provides a way to reference
-Engine structures that is more flexible than C pointers. Each Engine
-structure has an associated GUID which can be used to reference that
-structure. Engine GUIDs have the following features:
-
- at itemize
-
- at item
-The GUID is permanent, i.e., it persists between invocations of GnuCash.
-
- at item
-The GUID is guaranteed to be unique with the set of all Splits,
-Transactions, and Accounts in the hierarchy of which the structure
-is a member.
-
- at item
-With very high probability, the GUID is unique among all GUIDs
-created by any invocation of GnuCash, all over the world.
-
- at item
-GUIDs can be efficiently encoded in a string representation.
-
- at end itemize
-
-
- at menu
-* When to use GUIDs::
-* GUID Types::
-* How to use GUIDs::
-* GUIDs and GnuCash Entities::
-* The GUID Generator::
- at end menu
-
- at node When to use GUIDs, GUID Types, Globally Unique Identifiers, Globally Unique Identifiers
- at subsection When to use GUIDs
- at cindex When to use GUIDs
-
-Although GUIDs are very flexible, the engine structures like Accounts
-will probably continue to use C pointers for the forseeable future,
-since they are much faster (and in certain respects more convenient)
-than using GUIDs. In general, however, it is much safer to use GUIDs.
-In particular, you should consider using GUIDs if any of the following
-is true:
-
- at itemize
-
- at item
-You need to save a reference to an engine structure in a file.
-
- at item
-You need to save a reference to an engine structure that could
-be deleted in between accesses to the saved reference.
-
- at end itemize
-
-
- at node GUID Types, How to use GUIDs, When to use GUIDs, Globally Unique Identifiers
- at subsection GUID Types
- at tindex GNCIdType
-
-The GUIDs in GnuCash are typed using the enum @code{GNCIdType}.
-Possible values and their meanings for GUID types are:
-
- at table @code
-
- at item GNC_ID_NONE
-The GUID does not currently refer to a GnuCash entity, though it
-could refer to one in the future.
-
- at item GNC_ID_NULL
-The GUID does not, and never will, refer to a GnuCash entity.
-
- at item GNC_ID_ACCOUNT
-The GUID refers to an Account (@pxref{Accounts}).
-
- at item GNC_ID_TRANS
-The GUID refers to a Transation (@pxref{Transactions}).
-
- at item GNC_ID_SPLIT
-The GUID refers to a Split (@pxref{Splits}).
-
- at end table
-
- at deftypefun GNCIdType xaccGUIDType (const GUID * @var{guid})
-Return the type associated with @var{guid}.
- at end deftypefun
-
- at deftypefun {const GUID *} xaccGUIDNull (void)
-Return a GUID which is guaranteed to always have type @code{GNC_ID_NULL}.
- at end deftypefun
-
-
- at node How to use GUIDs, GUIDs and GnuCash Entities, GUID Types, Globally Unique Identifiers
- at subsection How to use GUIDs
-
-The Engine API functions which access the GUID for a specific entity
-return a pointer to the GUID. NOTE: Do not store the pointer
-itself! Instead, store a copy of the GUID. Storing the pointer itself
-would present some of the same problems as using the account pointer
-directly. Example:
-
- at example
-@{
- GUID saved_guid;
- Account *account;
-
- account = < something to get an Account pointer >
-
- saved_guid = *xaccAccountGetGUID(account);
-
- ...
-
- account = xaccAccountLookup(&saved_guid);
-
- ...
-@}
- at end example
-
-You can compare two GUIDs with the following functions.
-
- at deftypefun gboolean guid_equal (const GUID * @var{guid_1}, const GUID * @var{guid_2})
-Compare two guids and return TRUE if they are both non-NULL and equal.
- at end deftypefun
-
- at deftypefun gint guid_compare (const GUID * @var{g1}, const GUID * @var{g2})
-Return the @code{memcmp} of the two GUID's.
- at end deftypefun
-
-
-You can encode and decode GUIDs and their string representations using the
-next two functions.
-
- at deftypefun {const char *} guid_to_string (const GUID * @var{guid})
-Return a null-terminated string encoding of @var{guid}. String encodings
-of identifiers are hex numbers printed only with the characters @code{0}
-through @code{9} and @code{a} through @code{f}. The encoding will
-always be @code{GUID_ENCODING_LENGTH} characters long. The returned
-string must NOT be freed when no longer needed.
- at end deftypefun
-
- at deftypefun {char *} guid_to_string_buff (const GUID * @var{guid}, char * @var{buff})
-This routine does the same work as @code{guid_to_string}, except that the
-string is written into the memory pointed at by @var{buff}. The
-buffer must be at least GUID_ENCODING_LENGTH+1 characters long.
-This routine is handy for avoiding a malloc/free cycle.
-It returns a pointer to the @emph{end} of what was written.
-(i.e. it can be used like @code{stpcpy} during string concatenation)
- at end deftypefun
-
- at deftypefun gboolean string_to_guid (const char * @var{string}, GUID * @var{guid})
-Given a string, decode an id into @var{guid} if @var{guid} is
-non-NULL. The function returns TRUE if the string was a valid 32
-character hexadecimal number. This function accepts both upper and lower
-case hex digits. If the return value is FALSE, the effect on @var{guid}
-is undefined.
- at end deftypefun
-
-
-You can allocate and deallocate space for GUIDs using standard
-memory routines. However, if your code is allocating and deallocating
-lots of GUID objects, then the next two functions should be used.
-
- at deftypefun {GUID *} xaccGUIDMalloc (void)
-Return newly allocated memory for a GUID object. The memory must
-be freed with @code{xaccGUIDFree}. In general, this function is
-faster than using the standard libc allocators.
- at end deftypefun
-
- at deftypefun void xaccGUIDFree (GUID * @var{guid})
-Free the space for a GUID that was allocated with @code{xaccGUIDMalloc}.
- at end deftypefun
-
-
-You can use the following two functions to aid in using GUIDS in hash
-tables.
-
- at deftypefun guint guid_hash_to_guint (gconstpointer @var{ptr})
-Return a hash value suitable for use with a @code{GHashTable}.
- at var{ptr} must point to a GUID.
- at end deftypefun
-
- at deftypefun {GHashTable *} guid_hash_table_new (void)
-Return a new @code{GHashTable} which uses GUIDs as keys.
- at end deftypefun
-
-
- at node GUIDs and GnuCash Entities, The GUID Generator, How to use GUIDs, Globally Unique Identifiers
- at subsection GUIDs and GnuCash Entities
-
-This section documents a low-level API for associating entities with
-GUIDs. User code and general engine code should not use this API;
-instead use the API documented in the sections for the specific GnuCash
-entities such as Accounts and Transactions.
-
- at deftypefun void xaccGUIDNew (GUID * @var{guid})
-Generate a new guid. This function is guaranteed to return a guid that
-is unique within the scope of all GnuCash entities being managed by the
-the current invocation of GnuCash. GnuCash routines should always use
-this function and not @code{guid_new}!
- at end deftypefun
-
- at deftypefun {void *} xaccLookupEntity (const GUID * @var{guid}, GNCIdType @var{entity_type})
-Lookup an entity given an id and a type. If there is no entity
-associated with the id, or if it has a different type, NULL is returned.
- at end deftypefun
-
- at deftypefun void xaccStoreEntity (void * @var{entity}, const GUID * @var{guid}, GNCIdType entity_type)
-Store the given entity under the given id with the given type.
- at end deftypefun
-
- at deftypefun void xaccRemoveEntity (const GUID * @var{guid})
-Remove any existing association between an entity and the given id. The
-entity is not changed in any way.
- at end deftypefun
-
-
- at node The GUID Generator, , GUIDs and GnuCash Entities, Globally Unique Identifiers
- at subsection The GUID Generator
- at cindex The GUID Generator
-
-GUIDs are created by the GUID generator. The API for this generator is
-low-level and should not be used by user-code.
-
- at deftypefun void guid_init (void)
-Initialize the GUID generator with a variety of random sources including
-common system files and /dev/random.
- at end deftypefun
-
- at deftypefun void guid_init_with_salt (const void * @var{salt}, size_t @var{salt_len})
-Initialize the GUID generator with guid_init() and with the given
-sequence of arbitrary binary data.
- at end deftypefun
-
- at deftypefun void guid_init_only_salt (const void * @var{salt}, size_t @var{salt_len})
-Initialize the GUID generator using only the given sequence of arbitrary
-binary data. This provides a way to reliably obtain a given sequence of
-GUIDs.
- at end deftypefun
-
- at deftypefun void guid_new (GUID * @var{guid})
-Create a new GUID and store it in @var{guid}. This is a low-level function!
-GnuCash code should use @code{xaccGUIDNew}.
- at end deftypefun
-
-
- at node Numeric Library, Key-Value Pair Frames, Globally Unique Identifiers, Engine
- at section Numeric Library
- at cindex Numeric Library
- at tindex gnc_numeric
-
-=============== The documentation below for gnc_numeric is obsolete
- and has been superseeded by the gnc_numeric docs in the header file.
-=========================================
-
-Financial quantities in GnuCash (Split quantities and values) are stored
-as exact quantities measured in the smallest denominational unit of the
-appropriate currency. For example, 100.50 US Dollars would be stored as
-(10050 / 100) US Dollars. GnuCash uses the @code{gnc_numeric} datatype
-to store financial quantities.
-
-The @code{gnc_numeric} API provides data types and functions for
-manipulating exact numeric quantities. While the @code{gnc_numeric}
-library was developed to represent and operate on exact financial
-quantities in GnuCash, the library is also (hopefully) suitable for use
-in any application where exact numeric representation for rational
-numbers is needed.
-
-A @code{gnc_numeric} value represents a number in rational form, with a
-64-bit @code{long long} integer as numerator and denominator. If more
-precision, a higher-precision representation of irrational numbers, or a
-wider dynamic range is needed, a floating point format may be
-appropriate. There are reasonable rational approximations to common
-irrational constants (@pxref{Numeric Example}), but the transcendental
-functions have not been implemented for @code{gnc_numeric} objects.
-
- at menu
-* Standard Numeric Arguments::
-* Creating Numeric Objects::
-* Basic Arithmetic Operations::
-* Numeric Comparisons and Predicates::
-* Numeric Denominator Conversion::
-* Numeric Floating Point Conversion::
-* Numeric String Conversion::
-* Numeric Error Handling ::
-* Numeric Example::
- at end menu
-
- at node Standard Numeric Arguments, Creating Numeric Objects, Numeric Library, Numeric Library
- at subsection Standard Numeric Arguments
- at cindex Standard Numeric Arguments
-
-=============== The documentation below for gnc_numeric is obsolete
- and has been superseeded by the gnc_numeric docs in the header file.
-=========================================
-
-It is useful to specify a denominator in cases where it is known that
-the output value is of constrained precision. For example, monetary
-transactions must be executed in an integer number of the "smallest
-currency unit" of the transaction. In US Dollars, the smallest currency
-unit is the cent, and all monetary transactions must be done in units of
-cents. Therefore, any fractional cents in a computed price must be
-rounded away.
-
-Most of the @code{gnc_numeric} arithmetic functions take two arguments
-in addition to their numeric args: @var{denom}, which is the denominator
-to use in the output @code{gnc_numeric object}, and @var{how}, which
-describes how the arithmetic result is to be converted to that
-denominator. This combination of output denominator and rounding policy
-allows the results of financial and other exact computations to be
-properly rounded to the appropriate units.
-
-Valid values for @var{denom} are:
-
- at table @code
-
- at item n (positive int)
-Use the number @code{n} as the denominator of the output value.
-
- at item GNC_DENOM_RECIPROCAL (n)
-Use the value @code{1/n} as the denominator of the output value.
-
- at item GNC_DENOM_AUTO
-Compute an appropriate denominator automatically. Flags in the @var{how}
-argument will specify how to compute the denominator.
-
- at end table
-
-
-Valid values for @var{how} are bitwise combinations of zero or one
-"rounding instructions" with zero or one "denominator types".
-
-Rounding instructions control how fractional parts in the specified
-denominator affect the result. For example, if a computed result is
-"3/4" but the specified denominator for the return value is 2, should
-the return value be "1/2" or "2/2"?
-
-Possible rounding instructions are:
-
- at table @code
-
- at item GNC_RND_FLOOR
-Round toward -infinity
-
- at item GNC_RND_CEIL
-Round toward +infinity
-
- at item GNC_RND_TRUNC
-Truncate fractions (round toward zero)
-
- at item GNC_RND_PROMOTE
-Promote fractions (round away from zero)
-
- at item GNC_RND_ROUND
-Use unbiased ("banker's") rounding. This rounds to the nearest integer,
-and to the nearest even integer when there are two equidistant nearest
-integers. This is generally the one you should use for financial
-quantities.
-
- at item GNC_RND_ROUND_HALF_UP
-Round to the nearest integer, rounding away from zero when there are two
-equidistant nearest integers.
-
- at item GNC_RND_ROUND_HALF_DOWN
-Round to the nearest integer, rounding toward zero when there are two
-equidistant nearest integers.
-
- at item GNC_RND_NEVER
-Never round at all, and signal an error if there is a fractional result
-in a computation.
-
- at end table
-
-
-The denominator type specifies how to compute a denominator if
- at code{GNC_DENOM_AUTO} is specified as the @var{denom}. Valid denominator
-types are:
-
- at table @code
-
- at item GNC_DENOM_EXACT
-Use any denominator which gives an exactly correct ratio of numerator to
-denominator. Use EXACT when you do not wish to lose any information in
-the result but also do not want to spend any time finding the "best"
-denominator.
-
- at item GNC_DENOM_REDUCE
-Reduce the result value by common factor elimination, using the smallest
-possible value for the denominator that keeps the correct ratio. The
-numerator and denominator of the result are relatively prime. This can
-be computationally expensive for large fractions.
-
- at item GNC_DENOM_LCD
-Find the least common multiple of the arguments' denominators and use
-that as the denominator of the result.
-
- at item GNC_DENOM_FIXED
-All arguments are required to have the same denominator, that
-denominator is to be used in the output, and an error is to be signaled
-if any argument has a different denominator.
-
- at item GNC_DENOM_SIGFIG
-Round to the number of significant figures given in the rounding
-instructions by the GNC_DENOM_SIGFIGS () macro.
-
- at item GNC_DENOM_SIGFIGS (n)
-Use a value for the denominator that will keep at least @code{n}
-significant figures in the result.
-
- at end table
-
-
-To use traditional rational-number operational semantics (all results
-are exact and are reduced to relatively-prime fractions) pass the
-argument @code{GNC_DENOM_AUTO} as @var{denom} and @code{GNC_DENOM_REDUCE
-| GNC_RND_NEVER} as @var{how}.
-
-To enforce strict financial semantics (such that all operands must have
-the same denominator as each other and as the result), use
- at var{GNC_DENOM_AUTO} as @var{denom} and @code{GNC_DENOM_FIXED |
-GNC_RND_NEVER} as @var{how}.
-
-
- at node Creating Numeric Objects, Basic Arithmetic Operations, Standard Numeric Arguments, Numeric Library
-
-=============== The documentation below for gnc_numeric is obsolete
- and has been superseeded by the gnc_numeric docs in the header file.
-=========================================
-
- at subsection Creating Numeric Objects
- at cindex Creating Numeric Objects
-
- at deftypefun gnc_numeric gnc_numeric_create (int @var{num}, int @var{denom})
-Create a @code{gnc_numeric} object with a value of "@var{num} / @var{denom}".
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_zero ()
-Create a @code{gnc_numeric} object with a value of 0.
- at end deftypefun
-
-
- at node Basic Arithmetic Operations, Numeric Comparisons and Predicates, Creating Numeric Objects, Numeric Library
- at subsection Basic Arithmetic Operations
- at cindex Basic Arithmetic Operations
-
-See @ref{Standard Numeric Arguments} for a description of the @var{denom}
-and @var{how} arguments to each arithmetic function.
-
- at deftypefun gnc_numeric gnc_numeric_add (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how})
-Return the sum of @var{a} and @var{b}.
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_sub (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how})
-Return "@var{a} - @var{b}".
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_mul (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how})
-Return the product of @var{a} and @var{b}.
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_div (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how})
-Return "@var{a} / @var{b}".
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_neg (gnc_numeric @var{a})
-Return "- at var{a}".
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_abs (gnc_numeric @var{a})
-Return the absolute value of @var{a}.
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_add_fixed (gnc_numeric @var{a}, gnc_numeric @var{b})
-Equivalent to @code{gnc_numeric_add} on @var{a} and @var{b} with
- at code{GNC_DENOM_AUTO} for @var{denom} and @code{GNC_DENOM_FIXED |
-GNC_RND_NEVER} for @var{how}.
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_sub_fixed (gnc_numeric @var{a}, gnc_numeric @var{b})
-Equivalent to @code{gnc_numeric_sub} on @var{a} and @var{b} with
- at code{GNC_DENOM_AUTO} for @var{denom} and @code{GNC_DENOM_FIXED |
-GNC_RND_NEVER} for @var{how}.
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_add_with_error (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how}, {gnc_numeric *} @var{error})
-The same as @code{gnc_numeric_add}, but uses @var{error} for accumulating
-conversion roundoff error.
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_sub_with_error (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how}, {gnc_numeric *} @var{error})
-The same as @code{gnc_numeric_sub}, but uses @var{error} for accumulating
-conversion roundoff error.
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_mul_with_error (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how}, {gnc_numeric *} @var{error})
-The same as @code{gnc_numeric_mul}, but uses @var{error} for accumulating
-conversion roundoff error.
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_div_with_error (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how}, {gnc_numeric *} @var{error})
-The same as @code{gnc_numeric_div}, but uses @var{error} for accumulating
-conversion roundoff error.
- at end deftypefun
-
-
- at node Numeric Comparisons and Predicates, Numeric Denominator Conversion, Basic Arithmetic Operations, Numeric Library
- at subsection Numeric Comparisons and Predicates
- at cindex Numeric Comparisons and Predicates
-
- at deftypefun int gnc_numeric_zero_p (gnc_numeric @var{a})
-Returns 1 if @code{@var{a} == 0}, otherwise returns 0.
- at end deftypefun
-
- at deftypefun int gnc_numeric_positive_p (gnc_numeric @var{a})
-Returns 1 if @code{@var{a} > 0}, otherwise returns 0.
- at end deftypefun
-
- at deftypefun int gnc_numeric_negative_p (gnc_numeric @var{a})
-Returns 1 if @code{@var{a} < 0}, otherwise returns 0.
- at end deftypefun
-
- at deftypefun int gnc_numeric_compare (gnc_numeric @var{a}, gnc_numeric @var{b})
-Returns +1 if @code{@var{a} > @var{b}}, -1 if @code{@var{b} > @var{a}}, 0 if @code{@var{a} == @var{b}}.
- at end deftypefun
-
- at deftypefun int gnc_numeric_eq (gnc_numeric @var{a}, gnc_numeric @var{b})
-Returns 1 if @code{numerator(@var{a}) == numerator(@var{b})} and
- at code{denominator(@var{a}) == denominator(@var{b})}, otherwise returns 0.
- at end deftypefun
-
- at deftypefun int gnc_numeric_equal (gnc_numeric @var{a}, gnc_numeric @var{b})
-Returns 1 if the fraction represented by @var{a} is equal to the fraction
-represented by @var{b}, otherwise returns 0.
- at end deftypefun
-
- at deftypefun int gnc_numeric_same (gnc_numeric @var{a}, gnc_numeric @var{b}, gint64 @var{denom}, gint @var{how})
-Convert both @var{a} and @var{b} to @var{denom} (@pxref{Standard Numeric
-Arguments} and compare numerators of the result.
-
- at example
- For example, if @code{@var{a} == 7/16} and @code{@var{b} == 3/4},
- @code{gnc_numeric_same(@var{a}, @var{b}, 2, GNC_RND_TRUNC) == 1}
- because both 7/16 and 3/4 round to 1/2 under truncation. However,
- @code{gnc_numeric_same(@var{a}, @var{b}, 2, GNC_RND_ROUND) == 0}
- because 7/16 rounds to 1/2 under unbiased rounding but 3/4 rounds
- to 2/2.
- at end example
- at end deftypefun
-
-
- at node Numeric Denominator Conversion, Numeric Floating Point Conversion, Numeric Comparisons and Predicates, Numeric Library
-=============== The documentation below for gnc_numeric is obsolete
- and has been superseeded by the gnc_numeric docs in the header file.
-=========================================
-
- at subsection Numeric Denominator Conversion
- at cindex Numeric Denominator Conversion
-
- at deftypefun gnc_numeric gnc_numeric_convert (gnc_numeric @var{in}, gint64 @var{denom}, gint @var{how})
-Convert @var{in} to the specified denominator under standard arguments
- at var{denom} and @var{how}. @xref{Standard Numeric Arguments}.
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_convert_with_error (gnc_numeric @var{in}, gint64 @var{denom}, gint @var{how}, {gnc_numeric *} @var{error})
-Same as @code{gnc_numeric_convert}, but return a remainder value for
-accumulating conversion error.
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_reduce (gnc_numeric @var{in})
-Return @var{in} reduced by GCF reduction.
- at end deftypefun
-
-
- at node Numeric Floating Point Conversion, Numeric String Conversion, Numeric Denominator Conversion, Numeric Library
- at subsection Numeric Floating Point Conversion
- at cindex Numeric Floating Point Conversion
-
- at deftypefun gnc_numeric double_to_gnc_numeric (double @var{arg}, gint64 @var{denom}, gint @var{how})
-Convert a floating-point number to a @code{gnc_numeric}. Both @var{denom}
-and @var{how} are used as in arithmetic, but @code{GNC_DENOM_AUTO} is
-not recognized.
- at end deftypefun
-
- at deftypefun double gnc_numeric_to_double (gnc_numeric @var{arg})
-Convert @var{arg} to a @code{double} value.
- at end deftypefun
-
-
- at node Numeric String Conversion, Numeric Error Handling , Numeric Floating Point Conversion, Numeric Library
- at subsection Numeric String Conversion
- at cindex Numeric String Conversion
-
- at deftypefun {gchar *} gnc_numeric_to_string (gnc_numeric @var{n})
-Return a string representation of @var{n}. The string must be
-freed with @code{g_free}.
- at end deftypefun
-
- at deftypefun {const gchar *} string_to_gnc_numeric (const {gchar *} @var{str}, {gnc_numeric *} @var{n})
-Read a @code{gnc_numeric} from @var{str}, skipping any leading
-whitespace, and returning a pointer to just past the last byte
-read. Return NULL on error.
- at end deftypefun
-
-
- at node Numeric Error Handling , Numeric Example, Numeric String Conversion, Numeric Library
- at subsection Numeric Error Handling
- at cindex Numeric Error Handling
-
- at deftypefun int gnc_numeric_check (gnc_numeric @var{num})
-Check @var{num} for the possibility that it is an error signal rather
-than a proper value. Possible return codes are:
-
- at table @code
-
- at item GNC_ERROR_OK
-No error condition
-
- at item GNC_ERROR_ARG
-An improper argument was passed to a function
-
- at item GNC_ERROR_OVERFLOW
-An overflow occurred while calculating a result
-
- at item GNC_ERROR_DENOM_DIFF
- at code{GNC_DENOM_FIXED} was specified, but argument denominators differed.
-
- at item GNC_ERROR_REMAINDER
- at code{GNC_RND_NEVER} was specified, but the result could not be
-converted to the desired denominator without a remainder.
-
- at end table
-
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_numeric_error (int error_code)
-Create a @code{gnc_numeric} object that signals the error condition
-noted by @var{error_code} rather than a number.
- at end deftypefun
-
-
- at node Numeric Example, , Numeric Error Handling , Numeric Library
- at subsection Numeric Example
- at cindex Numeric Example
-
-=============== The documentation below for gnc_numeric is obsolete
- and has been superseeded by the gnc_numeric docs in the header file.
-=========================================
-
-The following program finds the best @code{gnc_numeric} approximation to
-the @file{math.h} constant @code{M_PI} given a maximum denominator. For
-large denominators, the @code{gnc_numeric} approximation is accurate to
-more decimal places than will generally be needed, but in some cases
-this may not be good enough. For example,
-
- at example
- M_PI = 3.14159265358979323846
- 245850922 / 78256779 = 3.14159265358979311599 (16 sig figs)
- 3126535 / 995207 = 3.14159265358865047446 (12 sig figs)
- 355 / 113 = 3.14159292035398252096 (7 sig figs)
- at end example
-
- at example
-#include <glib.h>
-#include "gnc-numeric.h"
-#include <math.h>
-
-int
-main(int argc, char ** argv)
-@{
- gnc_numeric approx, best;
- double err, best_err=1.0;
- double m_pi = M_PI;
- gint64 denom;
- gint64 max;
-
- sscanf(argv[1], "%Ld", &max);
-
- for (denom = 1; denom < max; denom++)
- @{
- approx = double_to_gnc_numeric (m_pi, denom, GNC_RND_ROUND);
- err = m_pi - gnc_numeric_to_double (approx);
- if (fabs (err) < fabs (best_err))
- @{
- best = approx;
- best_err = err;
- printf ("%Ld / %Ld = %.30f\n", gnc_numeric_num (best),
- gnc_numeric_denom (best), gnc_numeric_to_double (best));
- @}
- @}
-@}
- at end example
-
-
- at node Key-Value Pair Frames, Events, Numeric Library, Engine
- at section Key-Value Pair Frames
- at cindex Key-Value Pairs
-
-The number and types of data items which are associated with the
-financial abstractions (Accounts, Transactions, and Splits) can vary
-widely. For example, an Account which represents a user's checking
-account might need to store the bank name, a telephone number, and a
-username for online banking purposes. Another Account representing the
-user's ownership of a stock might need to store information about
-retrieving price quotes online such as the ticker symbol and the
-exchange.
-
-To meet this need for varying data storage, the GnuCash accounting
-entities use Key-Value Pair Frames (hereafter referred to as the
-datatype @code{kvp_frame}). A @code{kvp_frame} is a set of associations
-between character strings (keys) and @code{kvp_value} structures. A
- at code{kvp_value} is a union with possible types enumerated in the
- at code{kvp_value_t} enum which indicates the type of data stored in a
- at code{kvp_value} object.
-
- at menu
-* Key-Value Policy::
-* kvp_frame::
-* kvp_value::
-* kvp_list::
- at end menu
-
-
- at node Key-Value Policy, kvp_frame, Key-Value Pair Frames, Key-Value Pair Frames
- at subsection Key-Value Policy
- at cindex Key-Value Policy
-
-This section defines the policy that programmers should follow
-when using key-value pairs to store information. Because of the
-large amount of information which can potentially be stored using
-this mechanism, it is important to follow these guidelines so
-that order will be maintained.
-
-The following rules should be followed for using key-value pairs:
-
- at itemize
-
- at item
-The document @file{src/engine/kvp_doc.txt} should be used to document the
-use of keys and values. Please consult this document before planning any
-use of new keys.
-
- at item
-Key strings should be in all lower case with the '-' character
-separating words. If possible, use only alphanumeric characters and
-'-'. Example: @code{bank-info}. Because the '/' character is useful for
-describing keys in sub-frames (@code{bank-info/routing-number}), do not
-use the '/' character in key names.
-
- at item
-Favor longer, descriptive key strings over short ones. Example:
- at code{online-banking-info} is better than @code{onln-bnk}.
-
- at item
-Make use of the fact that frames can be stored in frames. If a group
-of keys are used for a related purpose, consider storing them together
-in a sub-frame.
-
- at item
-Values should generally not be accessed directly through keys, but
-should rather be accessed through specific API calls. The API calls
-do not necessarily need to part a part of the Engine API. For example,
-the GUI would probably define keys that the Engine does not need to
-know about.
-
- at item
-The same key should not be used for different engine structures (Accounts,
-Transactions, Splits), unless the key's value has the same type and the
-same basic purpose.
-
- at end itemize
-
-
- at node kvp_frame, kvp_value, Key-Value Policy, Key-Value Pair Frames
- at subsection kvp_frame
- at tindex kvp_frame
-
-A @code{kvp_frame} is the datatype used to associate key strings with
- at code{kvp_value} objects (@pxref{kvp_value}).
-
- at deftypefun kvp_frame* kvp_frame_new (void)
-Create and initialize a new @code{kvp_frame} object and return
-a pointer to it.
- at end deftypefun
-
- at deftypefun void kvp_frame_delete (kvp_frame * @var{frame})
-Free all memory associated with @var{frame}.
- at end deftypefun
-
- at deftypefun kvp_frame* kvp_frame_copy (const kvp_frame * frame)
-Return a deep copy of @var{frame}.
- at end deftypefun
-
- at deftypefun void kvp_frame_set_slot (kvp_frame * @var{frame}, const char * @var{key}, const kvp_value * @var{value})
-Associate @var{key} with @var{value} in @var{frame}.
- at end deftypefun
-
- at deftypefun void kvp_frame_set_slot_nc (kvp_frame * @var{frame}, const char * @var{key}, kvp_value * @var{value})
-Same as @code{kvp_frame_set_slot}, except that @var{value} is used
-directly, instead of being copied. This call transfers 'ownership'
-of @var{value} to @var{frame}.
- at end deftypefun
-
- at deftypefun kvp_value* kvp_frame_get_slot (kvp_frame * @var{frame}, const char * @var{key})
-Return the @code{kvp_value} object associated with @var{key}
-in @var{frame} or return @code{NULL} if there is no association
-for @var{key}. The value returned is not a copy.
- at end deftypefun
-
- at deftypefun void kvp_frame_set_slot_path (kvp_frame * @var{frame}, const kvp_value * @var{value}, const char * @var{first_key}, ...)
-Associate @var{value} with the ``key path'' specified by the variable
-argument list. Each key in the path except the last denotes a sub-frame
-which is associated with the given key. The variable list must be
-terminated with NULL.
- at end deftypefun
-
- at deftypefun void kvp_frame_set_slot_path_gslist (kvp_frame * @var{frame}, const kvp_value * @var{value}, GSList * @var{key_path})
-The same as @code{kvp_frame_set_slot_path}, except that the key path is
-specified using a GSList. All the keys in the list should be non-NULL.
- at end deftypefun
-
- at deftypefun {kvp_value *} kvp_frame_get_slot_path (kvp_frame * @var{frame}, const char * @var{first_key}, ...)
-Return the value associated with the key path, or @code{NULL} if none.
-The path is specified as in @code{kvp_frame_set_slot_path}.
- at end deftypefun
-
- at deftypefun {kvp_value *} kvp_frame_get_slot_path_gslist (kvp_frame * @var{frame}, GSList * @var{key_path})
-Return the value associated with the key path, or @code{NULL} if none.
-The path is specified as in @code{kvp_frame_set_slot_path_gslist}.
- at end deftypefun
-
- at deftypefun {kvp_frame *} kvp_frame_get_frame (kvp_frame * @var{frame}, ...)
-Works like @code{kvp_frame_get_slot_path}, but returns the last frame
-in the path. All the keys should refer to frames. If the frame path
-does not exist, it is created.
- at end deftypefun
-
- at deftypefun {kvp_frame *} kvp_frame_get_frame_gslist (kvp_frame * @var{frame}, GSList * @var{key_path})
-Works like @code{kvp_frame_get_slot_path_gslist}, but returns the last
-frame in the path. All the keys should refer to frames. If the frame
-path does not exist, it is created.
- at end deftypefun
-
- at deftypefun {kvp_frame *} kvp_frame_get_frame_slash (kvp_frame * @var{frame}, const char * @var{path})
-Works like @code{kvp_frame_get_frame}, but the frame path is specified
-as a single string where the keys are separated by slashes; thus, for
-example: @code{/this/is/a/valid/path} and @code{///so//is////this/}.
-Multiple slashes are compresed and a leading slash is optional. The
-pointers @code{.} and @code{..} are @emph{not} followed/obeyed. (This
-is arguably a bug that needs fixing).
- at end deftypefun
-
-
- at node kvp_value, kvp_list, kvp_frame, Key-Value Pair Frames
- at subsection kvp_value
- at tindex kvp_value
- at tindex kvp_value_t
-
-The @code{kvp_value} object stores the 'value' part of a key-value
-association in a @code{kvp_frame} object.
-
- at deftypefun void kvp_value_delete (kvp_value * @var{value})
-Free all of the memory associated with @var{value}.
- at end deftypefun
-
- at deftypefun kvp_value* kvp_value_copy (const kvp_value * @var{value})
-Return a deep copy of @var{value}.
- at end deftypefun
-
- at deftypefun kvp_value_t kvp_value_get_type (const kvp_value * @var{value})
-Return the type of value stored in @var{value}.
- at end deftypefun
-
-A @code{kvp_value_t} enum must have one of the following values:
-
- at table @code
-
- at item KVP_TYPE_NONE
-Indicates the abscence of a value in a @code{kvp_frame}.
-
- at item KVP_TYPE_INT64
-A @code{gint64} value.
-
- at item KVP_TYPE_FLOAT64
-A @code{double} value.
-
- at item KVP_TYPE_STRING
-A @code{char *} value of arbitrary length.
-
- at item KVP_TYPE_GUID
-A @code{GUID} value. @xref{Globally Unique Identifiers}.
-
- at item KVP_TYPE_BINARY
-Arbitrary binary data.
-
- at item KVP_TYPE_LIST
-A @code{kvp_list} item which contains a list of @code{kvp_value} items.
-
- at item KVP_TYPE_FRAME
-A @code{kvp_frame} object. Thus, frames may contain other frames in a
-recursive manner.
-
- at end table
-
- at subsubsection Value Constructors
-
-The following functions create and return @code{kvp_value} objects with
-particular values. In the case of pointer arguments, deep copies are
-performed.
-
- at deftypefun kvp_value* kvp_value_new_int64 (gint64 @var{value})
- at end deftypefun
- at deftypefun kvp_value* kvp_value_new_float64 (double @var{value})
- at end deftypefun
- at deftypefun kvp_value* kvp_value_new_string (const char * @var{value})
- at end deftypefun
- at deftypefun kvp_value* kvp_value_new_guid (const GUID * @var{guid})
- at end deftypefun
- at deftypefun kvp_value* kvp_value_new_binary (const void * @var{data}, int @var{datasize})
- at end deftypefun
- at deftypefun kvp_value* kvp_value_new_list (const kvp_list * @var{value})
- at end deftypefun
- at deftypefun kvp_value* kvp_value_new_frame (const kvp_frame * @var{value});
- at end deftypefun
-
- at subsubsection Value Accessors
-
-The following functions access the value of a given @code{kvp_value}
-object. If the type of the object does not correspond to that named
-in the function, @code{NULL}, @code{0}, or @code{0.0} is returned
-as appropriate.
-
- at deftypefun gint64 kvp_value_get_int64 (const kvp_value * @var{value})
- at end deftypefun
- at deftypefun double kvp_value_get_float64 (const kvp_value * @var{value})
- at end deftypefun
- at deftypefun char* kvp_value_get_string (const kvp_value * @var{value})
- at end deftypefun
- at deftypefun GUID* kvp_value_get_guid (const kvp_value * @var{value})
- at end deftypefun
- at deftypefun void* kvp_value_get_binary (const kvp_value * @var{value}, int * @var{size_return})
- at end deftypefun
- at deftypefun kvp_list* kvp_value_get_list (const kvp_value * @var{value})
- at end deftypefun
- at deftypefun kvp_frame* kvp_value_get_frame (const kvp_value * @var{value})
- at end deftypefun
-
-
- at node kvp_list, , kvp_value, Key-Value Pair Frames
- at subsection kvp_list
- at tindex kvp_list
-
-A @code{kvp_list} object abstract a list of @code{kvp_value} objects.
-
- at deftypefun kvp_list* kvp_list_new ()
-Return a newly allocated @code{kvp_list} object.
- at end deftypefun
-
- at deftypefun void kvp_list_delete (kvp_list * @var{list})
-Free all memory associated with @var{list}, including the
- at code{kvp_value} objects in @var{list}.
- at end deftypefun
-
- at deftypefun kvp_list* kvp_list_copy (const kvp_list * @var{list})
-Return a deep copy of @var{list}.
- at end deftypefun
-
- at deftypefun gboolean kvp_list_null_p (const kvp_list * @var{list})
-Return @code{TRUE} if @var{list} is the empty list.
- at end deftypefun
-
- at deftypefun kvp_value* kvp_list_car (kvp_list * @var{list})
-If @var{list} is @code{NULL} or the empty list, return @code{NULL}.
-Otherwise, return the first @code{kvp_value} object in the list.
- at end deftypefun
-
- at deftypefun kvp_list* kvp_list_cdr (kvp_list * @var{list})
-If @var{list} is @code{NULL} or the empty list, return @code{NULL}.
-Otherwise, return a @code{kvp_list} object consisting of @var{list}
-with the first value removed. NOTE: the returned list is not a copy!
- at end deftypefun
-
- at deftypefun kvp_list* kvp_list_cons (kvp_value * @var{car}, kvp_list * @var{cdr})
-If either @var{car} or @var{cdr} is @code{NULL}, return @code{NULL}. Otherwise,
-return a @code{kvp_list} object consisting of the value of @var{car} followed
-by the values of @var{cdr}. This function uses 'hand-over' semantics, i.e.,
-the arguments @var{car} and @var{cdr} are no longer the responsibility of
-the caller and should not be accessed after the function returns.
- at end deftypefun
-
-
- at node Events, Commodities, Key-Value Pair Frames, Engine
- at section Events
-
-The Engine supports the concept of @dfn{Events} which notify
-external code when engine entities are created, modified, or
-destroyed.
-
-User code can register event handers which are invoked for each event,
-giving information about the specific engine entity generating the event
-and the nature of the event (creation, modification, or deletion).
-
-
- at menu
-* Event API::
- at end menu
-
-
- at node Event API, , Events, Events
- at subsection Event API
- at tindex GNCEngineEventType
-
-Engine events are classified using the @code{GNCEngineEventType}
-bitmask which has the following predefined values:
-
- at table @code
-
- at item GNC_EVENT_NONE
-A null value.
-
- at item GNC_EVENT_CREATE
-Indicates an entity has been created.
-
- at item GNC_EVENT_MODIFY
-Indicates an entity has been changed in some way.
-
- at item GNC_EVENT_DESTROY
-Indicates an entity is being destroyed.
-
- at item GNC_EVENT_ALL
-The boolean OR of @code{GNC_EVENT_CREATE}, @code{GNC_EVENT_MODIFY},
-and @code{GNC_EVENT_DESTROY}.
-
- at end table
-
-Event handlers are functions with the following type:
-
- at deftp {Data type} GNCEngineEventHandler void (*) (GUID * @var{entity}, GNCEngineEventType @var{event_type}, gpointer @var{user_data})
-A callback invoked when an engine event occurs. @var{entity} is the
- at code{GUID} of the entity generating the event. @var{event_type} is
-one of @code{GNC_EVENT_CREATE}, @code{GNC_EVENT_MODIFY}, or
- at code{GNC_EVENT_DESTROY}. @var{user_data} is the user data parameter
-supplied when the handler was registered.
- at end deftp
-
- at deftypefun gint gnc_engine_register_event_handler (GNCEngineEventHandler @var{handler}, gpointer @var{user_data})
-Register a handler for engine events. The return value is an identifier used
-to specify this handler in other API calls.
- at end deftypefun
-
- at deftypefun void gnc_engine_unregister_event_handler (gint @var{handler_id})
-Unregister the event handler specified by @var{handler_id}.
- at end deftypefun
-
- at deftypefun void gnc_engine_suspend_events (void)
-Suspend all engine events. This function may be called multiple
-times. To resume event generation, an equal number of calls to
- at code{gnc_engine_resume_events} must be made.
- at end deftypefun
-
- at deftypefun void gnc_engine_resume_events (void)
-Resume engine event generation.
- at end deftypefun
-
-
- at node Commodities, Commodity Tables, Events, Engine
- at section Commodities
- at tindex gnc_commodity
-
-A Commodity is the Engine abstraction of a tradable quantity,
-like a national currency or shares of a stock. A commodity
-object contains the following pieces of information:
-
- at table @asis
-
- at item A mnemonic name
-The `short' name for the commodity. For national currencies
-this is the 3-letter ISO4217 code (USD, AUD, etc.). For stocks
-this is generally the exchange symbol (RHAT, IBM, etc.).
-
- at item A namespace
-A string identifying the context in which the mnemonic is meaninful.
-
- at item A full name
-The `long' name for the commodity, such as "US Dollar" or "IBM Common
-Stock".
-
- at item A printable name
-The name used to print out a string describing the commodity to
-a user. This name is generally long -- in some contexts it may
-be better to use the mnemonic instead. The printable name is
-determined by the namespace and mnemonic.
-
- at item A unique name
-A canonical name for the commodity that cannot be identical to
-another commodity's unique name. The unique name is determined
-by the namespace and mnemonic.
-
- at item An exchange code
-A code used to identify the commodity in its namespace context.
-For example, stocks have a unique code assigned to them by the
-exchange they are listed on.
-
- at item A fraction
-An integer N which specifies that 1/N is generally the smallest
-fraction of the commodity which can be traded. For example, most
-currencies are tradable in 1/100ths, so the fraction would be 100.
-
- at end table
-
- at menu
-* General Commodity API::
-* Commodity Getters::
-* Commodity Setters::
- at end menu
-
-
- at node General Commodity API, Commodity Getters, Commodities, Commodities
- at subsection General Commodity API
-
- at deftypefun {gnc_commodity *} gnc_commodity_new (const char * @var{fullname}, const char * @var{namespace}, const char * @var{mnemonic}, const char * @var{exchange_code}, int @var{fraction})
-Create and return a new commodity object with the given values, or
- at code{NULL} if any of the values are invalid.
- at end deftypefun
-
- at deftypefun void gnc_commodity_destroy (gnc_commodity * @var{cm})
-Destroy the given commodity and free all associated memory.
- at end deftypefun
-
- at deftypefun gboolean gnc_commodity_equiv (const gnc_commodity * @var{a}, const gnc_commodity * @var{b})
-Return true if the two given commodities are equivalent. Two commodities
-are equivalent when they have the same namespace and the same mnemonic.
- at end deftypefun
-
-
- at node Commodity Getters, Commodity Setters, General Commodity API, Commodities
- at subsection Commodity Getters
-
- at deftypefun {const char *} gnc_commodity_get_mnemonic (const gnc_commodity * @var{cm})
-Return the mnemonic of @var{cm}.
- at end deftypefun
-
- at deftypefun {const char *} gnc_commodity_get_namespace (const gnc_commodity * @var{cm})
-Return the namespace of @var{cm}.
- at end deftypefun
-
- at deftypefun {const char *} gnc_commodity_get_fullname (const gnc_commodity * @var{cm})
-Return the full name of @var{cm}.
- at end deftypefun
-
- at deftypefun {const char *} gnc_commodity_get_printname (const gnc_commodity * @var{cm})
-Return the print name of @var{cm}.
- at end deftypefun
-
- at deftypefun {const char *} gnc_commodity_get_exchange_code (const gnc_commodity * @var{cm})
-Return the exchange code of @var{cm}.
- at end deftypefun
-
- at deftypefun {const char *} gnc_commodity_get_unique_name (const gnc_commodity * @var{cm})
-Return the unique name of @var{cm}.
- at end deftypefun
-
- at deftypefun int gnc_commodity_get_fraction (const gnc_commodity * @var{cm})
-Return the smallest tradable fraction of @var{cm}.
- at end deftypefun
-
-
- at node Commodity Setters, , Commodity Getters, Commodities
- at subsection Commodity Setters
-
- at deftypefun void gnc_commodity_set_mnemonic (gnc_commodity * @var{cm}, const char * @var{mnemonic})
-Set the mnemonic of @var{cm} to @var{mnemonic}.
- at end deftypefun
-
- at deftypefun void gnc_commodity_set_namespace (gnc_commodity * @var{cm}, const char * @var{namespace})
-Set the namespace of @var{cm} to @var{namespace}.
- at end deftypefun
-
- at deftypefun void gnc_commodity_set_fullname (gnc_commodity * @var{cm}, const char * @var{fullname})
-Set the fullname of @var{cm} to @var{fullname}.
- at end deftypefun
-
- at deftypefun void gnc_commodity_set_exchange_code (gnc_commodity * @var{cm}, const char * @var{exchange_code})
-Set the exchange code of @var{cm} to @var{exchange_code}.
- at end deftypefun
-
- at deftypefun void gnc_commodity_set_fraction (gnc_commodity * @var{cm}, int @var{smallest_fraction})
-Set the fraction of @var{cm} to @var{fraction}.
- at end deftypefun
-
-
- at node Commodity Tables, Prices, Commodities, Engine
- at section Commodity Tables
- at tindex gnc_commodity_table
-
-A Commodity Table holds a set of commodities and allows user code
-to add, remove, and access the commodities in the table.
-
-There is a single, global Commodity Table used by the Engine.
-
- at menu
-* General Commodity Table API::
-* Commodity Table Access API::
-* Commodity Table Modification API::
- at end menu
-
-
- at node General Commodity Table API, Commodity Table Access API, Commodity Tables, Commodity Tables
- at subsection General Commodity Table API
-
- at deftypefun {gnc_commodity_table *} gnc_commodity_table_new (void)
-Allocate and initialize a @code{gnc_commodity_table}. The returned
-table must be destroyed with @code{gnc_commodity_table_destroy}.
- at end deftypefun
-
- at deftypefun void gnc_commodity_table_destroy (gnc_commodity_table * @var{table})
-Destroy @var{table} and all associated resources, including all
-Commodity objects in the table.
- at end deftypefun
-
- at deftypefun {gnc_commodity_table *} gnc_engine_commodities (void)
-Return the global engine commodity table.
- at end deftypefun
-
-
- at node Commodity Table Access API, Commodity Table Modification API, General Commodity Table API, Commodity Tables
- at subsection Commodity Table Access API
-
- at deftypefun {gnc_commodity *} gnc_commodity_table_lookup (const gnc_commodity_table * @var{table}, const char * @var{namespace}, const char * @var{mnemonic})
-Look up a commodity in @var{table} given the namespace and the mnemonic.
-If no such commodity exists, @code{NULL} is returned.
- at end deftypefun
-
- at deftypefun {gnc_commodity *} gnc_commodity_table_find_full (const gnc_commodity_table * @var{table}, const char * @var{namespace}, const char * @var{fullnam}e)
-Look up a commodity in @var{table} given the namespace and the full name.
-If no such commodity exists, @code{NULL} is returned.
- at end deftypefun
-
- at deftypefun int gnc_commodity_table_has_namespace (const gnc_commodity_table * @var{table}, const char * @var{namespace})
-Return true if @var{table} has the namespace @var{namespace}.
- at end deftypefun
-
- at deftypefun guint gnc_commodity_table_get_size (gnc_commodity_table * @var{table})
-Return the total number of commodities stored in @var{table}.
- at end deftypefun
-
- at deftypefun guint gnc_commodity_table_get_number_of_namespaces (gnc_commodity_table * @var{table})
-Return the number of distinct namespaces in @var{table}.
- at end deftypefun
-
- at deftypefun {GList *} gnc_commodity_table_get_namespaces (const gnc_commodity_table * @var{table})
-Return a list of the distinct namespaces in @var{table}. The list should
-be freed with @code{g_list_free} but the namespaces should not be freed
-or modified.
- at end deftypefun
-
- at deftypefun {GList *} gnc_commodity_table_get_commodities (const gnc_commodity_table * @var{table}, const char * @var{namespace})
-Return a list of the commodities under @var{namespace} in @var{table}.
-The list should be freed with @code{g_list_free} but the commodities
-should not be freed.
- at end deftypefun
-
-
- at node Commodity Table Modification API, , Commodity Table Access API, Commodity Tables
- at subsection Commodity Table Modification API
-
- at deftypefun {gnc_commodity *} gnc_commodity_table_insert (gnc_commodity_table * @var{table}, gnc_commodity * @var{comm})
-Add commodity @var{comm} to @var{table}. If @var{comm}'s namespace is
-not in @var{table}, the namespace will be added. This function has
-hand-over semantics, i.e., @var{table} assumes responsibility for
- at var{comm}. @var{comm} may even be destroyed by this call! The function
-returns the actual commodity added as a result of the call. It may not
-be the same object as @var{comm}, but will be equivalent to @var{comm}.
- at end deftypefun
-
- at deftypefun void gnc_commodity_table_remove (gnc_commodity_table * @var{table}, gnc_commodity * @var{comm})
-Remove the given commodity from @var{table}. @var{comm} is not modified
-or destroyed.
- at end deftypefun
-
- at deftypefun void gnc_commodity_table_add_namespace (gnc_commodity_table * @var{table}, const char * @var{namespace})
-Add @var{namespace} to @var{table}.
- at end deftypefun
-
- at deftypefun void gnc_commodity_table_delete_namespace (gnc_commodity_table * @var{table}, const char * @var{namespace})
-Delete @var{namespace} from @var{table} including all associated
-commodities.
- at end deftypefun
-
- at deftypefun void gnc_commodity_table_remove_non_iso (gnc_commodity_table * @var{table})
-Remove and destroy all commodities in @var{table} which are not in the
-ISO4217 namespace.
- at end deftypefun
-
-
- at node Prices, Price Databases, Commodity Tables, Engine
- at section Prices
- at tindex GNCPrice
-
-A Price is the Engine abstraction of an "instantaneous" price quote for a
-given commodity with respect to another commodity. For example, a given
-price might represent the value of LNUX in USD on 2001-02-03. A Price
-contains the following pieces of information:
-
- at table @asis
-
- at item A GUID
-A GUID uniquely identifying the GNCPrice.
-
- at item A commodity
-The commodity being priced.
-
- at item A currency
-The denomination of the value of the item being priced.
-
- at item A value
-The value of the item being priced.
-
- at item A time
-The time the price was valid.
-
- at item A source
-A string describing the source of the quote. These strings will have a
-form like this: "Finance::Quote", "user:misc", "user:foo", etc. If the
-quote came from a user, as a matter of policy, you @emph{must} prefix
-the string you give with "user:". For now, the only other reserved
-values are "Finance::Quote" and "old-file-import".
-
- at item A type
-A string describing the type of quote -- types possible right now are
-"bid", "ask", "last", "nav", and "unknown".
-
- at end table
-
-
- at menu
-* Price Implementation Details::
-* General Price API::
-* Price Getters::
-* Price Setters::
- at end menu
-
-
- at node Price Implementation Details, General Price API, Prices, Prices
- at subsection Price Implementation Details
-
-For the source and type fields, @code{NULL} and the empty string are
-considered the same, so if one of these is the empty string then it
-might be @code{NULL} after a file save/restore.
-
-GNCPrices are reference counted. When you create a price or or clone
-one, the new price's reference count is set to 1. When you are finished
-with a price, call @code{gnc_price_unref}. If you hand the price pointer
-to some other code that needs to keep it, make sure it calls
- at code{gnc_price_ref} to indicate its interest in that price, and calls
- at code{gnc_price_unref} when it's finished with the price. For those
-unfamiliar with reference counting, basically each price stores an
-integer count which starts at 1 and is incremented every time someone
-calls @code{gnc_price_ref}. Conversely, the count is decremented every
-time someone calls @code{gnc_price_unref}. If the count ever reaches 0,
-the price is destroyed.
-
-All of the getters return data that's internal to the GNCPrice,
-not copies, so don't free or modify these values.
-
-All of the setters store copies of the data given, with the exception of
-the commodity field which just stores the pointer given. It is assumed
-that commodities are a global resource and are pointer unique.
-
-
- at node General Price API, Price Getters, Price Implementation Details, Prices
- at subsection General Price API
-
- at deftypefun {GNCPrice *} gnc_price_create (void)
-Return a newly allocated and initialized price with a reference count of
-1. The price should be dereferenced with @code{gnc_price_unref} when no
-longer needed, but the price should not be freed by user code.
- at end deftypefun
-
- at deftypefun {GNCPrice *} gnc_price_clone (GNCPrice * @var{p})
-Return a newly allocated price that's a content-wise duplicate of
- at var{p}. The returned clone will have a reference count of 1.
- at end deftypefun
-
- at deftypefun void gnc_price_ref (GNCPrice * @var{p})
-Increase the reference count of @var{p} by 1.
- at end deftypefun
-
- at deftypefun void gnc_price_unref (GNCPrice * @var{p})
-Decrease the reference coutn of @var{p} by 1. If the
-resulting count is 0, @var{p} will be destroyed.
- at end deftypefun
-
- at deftypefun {GNCPrice *} gnc_price_lookup (const GUID * @var{guid})
-Lookup and return the price associated with @var{guid}, or @code{NULL}
-if there is no such price.
- at end deftypefun
-
-
- at node Price Getters, Price Setters, General Price API, Prices
- at subsection Price Getters
-
- at deftypefun {const GUID *} gnc_price_get_guid (GNCPrice * @var{p})
-Return the GUID of @var{p}.
- at end deftypefun
-
- at deftypefun {gnc_commodity *} gnc_price_get_commodity (GNCPrice * @var{p})
-Return the commodity of @var{p}.
- at end deftypefun
-
- at deftypefun {gnc_commodity *} gnc_price_get_currency (GNCPrice * @var{p})
-Return the currency of @var{p}.
- at end deftypefun
-
- at deftypefun Timespec gnc_price_get_time (GNCPrice * @var{p})
-Return the time of @var{p}.
- at end deftypefun
-
- at deftypefun {const char *} gnc_price_get_source (GNCPrice * @var{p})
-Return the source of @var{p}.
- at end deftypefun
-
- at deftypefun {const char *} gnc_price_get_type (GNCPrice * @var{p})
-Return the type of @var{p}.
- at end deftypefun
-
- at deftypefun gnc_numeric gnc_price_get_value (GNCPrice * @var{p})
-Return the value of @var{p}.
- at end deftypefun
-
- at deftypefun gint32 gnc_price_get_version (GNCPrice * @var{p})
-Return the version of @var{p}.
- at end deftypefun
-
-
- at node Price Setters, , Price Getters, Prices
- at subsection Price Setters
-
-Invocations of the setters should be wrapped with calls to
- at code{gnc_price_begin_edit} and @code{gnc_price_commit_edit}. The
-begin/commit calls help ensure that the local price db is synchronized
-with the backend.
-
- at deftypefun void gnc_price_begin_edit (GNCPrice * @var{p})
-Begin a sequence of changes to @var{p}.
- at end deftypefun
-
- at deftypefun void gnc_price_commit_edit (GNCPrice * @var{p})
-End a sequence of changes to @var{p}.
- at end deftypefun
-
- at deftypefun void gnc_price_set_commodity (GNCPrice * @var{p}, gnc_commodity * @var{c})
-Set the commodity of @var{p} to @var{c}.
- at end deftypefun
-
- at deftypefun void gnc_price_set_currency (GNCPrice * @var{p}, gnc_commodity * @var{c})
-Set the currency of @var{p} to @var{c}.
- at end deftypefun
-
- at deftypefun void gnc_price_set_time (GNCPrice * @var{p}, Timespec @var{t})
-Set the time of @var{p} to @var{t}.
- at end deftypefun
-
- at deftypefun void gnc_price_set_source (GNCPrice * @var{p}, const char * @var{source})
-Set the source of @var{p} to @var{source}.
- at end deftypefun
-
- at deftypefun void gnc_price_set_type (GNCPrice * @var{p}, const char * @var{type})
-Set the type of @var{p}to @var{type}.
- at end deftypefun
-
- at deftypefun void gnc_price_set_value (GNCPrice * @var{p}, gnc_numeric @var{value})
-Set the value of @var{p} to @var{value}.
- at end deftypefun
-
- at deftypefun void gnc_price_set_version (GNCPrice * @var{p}, gint32 @var{versn})
-Set the version of @var{p} to @var{versn}.
- at end deftypefun
-
-
- at node Price Databases, Splits, Prices, Engine
- at section Price Databases
- at tindex GNCPriceDB
-
-A Price Database stores GNCPrices and allows prices to be looked
-up based on currency, commodity, and time.
-
-
- at menu
-* Price Lists::
-* General Price Database API::
- at end menu
-
-
- at node Price Lists, General Price Database API, Price Databases, Price Databases
- at subsection Price Lists
-
-Price Lists are used by Price Databases to organize prices for a given
-commodity and currency. A Price List is a list of prices with the same
-commodity and currency, sorted by decreasing time (earlier prices come
-later in the list).
-
- at deftypefun gboolean gnc_price_list_insert (GList ** @var{prices}, GNCPrice * @var{p})
-Insert price @var{p} into the list @var{prices}, calling
- at var{gnc_price_ref} on @var{p} during the process.
- at end deftypefun
-
- at deftypefun gboolean gnc_price_list_remove (GList ** @var{prices}, GNCPrice * @var{p})
-Remove price @var{p} from the list @var{prices}, calling
- at code{gnc_price_unref} on @var{p} during the process.
- at end deftypefun
-
- at deftypefun void gnc_price_list_destroy (GList * @var{prices})
-Destroy the price list @var{prices}, calling @code{gnc_price_unref}
-on all the prices in the list.
- at end deftypefun
-
-
- at node General Price Database API, , Price Lists, Price Databases
- at subsection General Price Database API
-
- at deftypefun {GNCPriceDB *} gnc_pricedb_create (void)
-Create and return a new price database.
- at end deftypefun
-
- at deftypefun void gnc_pricedb_destroy (GNCPriceDB * @var{db})
-Destroy the price database @var{db} and unreference all of
-the prices it contains. This may not deallocate all of those
-prices; other code may still be holding references to them.
- at end deftypefun
-
- at deftypefun gboolean gnc_pricedb_add_price (GNCPriceDB * @var{db}, GNCPrice * @var{p})
-Add the price @var{p} to @var{db}. This will increase the
-reference count of @var{p}, so user code may safely drop
-its reference to the price (i.e. call @code{gnc_price_unref})
-if the call succeeds (returns true).
- at end deftypefun
-
- at deftypefun gboolean gnc_pricedb_remove_price (GNCPriceDB * @var{db}, GNCPrice * @var{p})
-Removes the price @var{p} from the price database @var{db}. Returns true
-if successful and false otherwise.
- at end deftypefun
-
-
- at node Splits, Transactions, Price Databases, Engine
- at section Splits
- at tindex Split
-
-A Split is the Engine abstraction of an accounting entry in an Account
-Ledger. In accounting terms, a Split is a Ledger Entry. As such, it
-contains the following pieces of information:
-
- at table @asis
-
- at item A parent Account
-The Account of which it is an entry.
-
- at item A parent Transaction.
-In accounting terms, this is the Journal Entry which this Ledger Entry
-is linked to.
-
- at item A 'share quantity'
-This is the number of 'shares' which have been debited to the parent
-Account. This quantity may be negative, in which case the Split
-represents a 'credit'. Shares are given in units of the security of the
-Account, unless the security field is NULL, in which case shares are
-given in units of the Account currency. @xref{Accounts}.
-
- at item A 'value'
-This represents the value of the shares in units of the currency of
-the Account. If the currency and the security are the same, or the
-security field is NULL, the value and share quantity must be equal.
-
- at item A 'reconciled' flag
-This flag represents the reconciled status of the Split. Possible
-reconciliation states for a Split are:
-
- @table @asis
-
- @item Not Reconciled
- The Split has not been reconciled or cleared.
-
- @item Cleared
- The Split has been cleared, but not reconciled.
-
- @item Reconciled
- The Split has been reconciled with a statement.
-
- @item Frozen
- The Split has been frozen into the accounting period.
-
- @end table
-
- at end table
-
-In addition to the above, Splits contain a Memo field, an Action
-field, and a key-value pair frame. The Memo and Action fields are for
-arbitrary user input. See src/engine/kvp_frame.txt for the names of
-keys that have already been reserved for use in the frame.
-
-
- at menu
-* General Split API::
-* Split Getters::
-* Split Setters::
- at end menu
-
- at node General Split API, Split Getters, Splits, Splits
- at subsection General Split API
-
- at deftypefun {Split *} xaccMallocSplit (void)
-Allocate, initialize, and return a new Split.
- at end deftypefun
-
- at deftypefun void xaccSplitDestroy (Split * @var{split})
-Update @var{split}'s parent Account and Transaction in a consistent
-manner, completely unlinking of @var{split} and freeing its memory. The
-goal of this routine is to perform the removal and destruction of the
-Split in an atomic fashion, with no chance of accidentally leaving the
-accounting structure out-of-balance or otherwise inconsistent.
-
-If the deletion of the Split leaves the Transaction with no Splits, then
-the Transaction will be marked for deletion, but will not be deleted
-until the @code{xaccTransCommitEdit()} routine is called.
- at end deftypefun
-
- at deftypefun {const GUID *} xaccSplitGetGUID (Split * @var{split})
-Return the GUID of @var{split}.
- at end deftypefun
-
- at deftypefun {Split *} xaccSplitLookup (const GUID * @var{guid})
-Return the split associated with @var{GUID}, or @code{NULL} if there is
-no such split.
- at end deftypefun
-
- at deftypefun void xaccSplitMakeStockSplit (Split * @var{split})
-Modify @var{split} to be an ``official'' stock-split split. Among other
-things, this involves clearing the value of the split to 0.
- at end deftypefun
-
-
- at node Split Getters, Split Setters, General Split API, Splits
- at subsection Split Getters
-
- at deftypefun {Account *} xaccSplitGetAccount (Split * @var{split})
-Return the parent Account of @var{split}.
- at end deftypefun
-
- at deftypefun {Transaction *} xaccSplitGetParent (Split * @var{split})
-Return the parent Transaction of @var{split}.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccSplitGetShareAmount (Split * @var{split})
-Return the 'share quantity' of @var{split}.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccSplitGetSharePrice (Split * @var{split})
-Return the 'share price' of @var{split}, which is the value
-divided by the share quantity.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccSplitGetValue (Split * @var{split})
-Return the value of @var{split}.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccSplitGetBaseValue (Split * @var{split}, const char * @var{base_currency})
-Return either the share quantity or the value of @var{split}, depending
-upon whether @var{base_currency} matches the security or currency of the
-parent Account, respectively. No other value for @var{base_currency} is
-legal.
- at end deftypefun
-
- at deftypefun char xaccSplitGetReconcile (Split * @var{split})
-Return the value of the reconcile flag in @var{split}. Possible
-values for the flag are:
-
- @table @code
-
- @item NREC
- Not Reconciled
-
- @item CREC
- Cleared
-
- @item YREC
- Reconciled
-
- @item FREC
- Frozen
-
- @end table
-
- at end deftypefun
-
- at deftypefun void xaccSplitGetDateReconciledTS (Split * @var{split}, Timespec * @var{ts})
-Fill @var{ts} with the reconciled date of @var{split}.
- at end deftypefun
-
- at deftypefun {const char *} xaccSplitGetMemo (Split * @var{split})
-Return the Memo field of @var{split}.
- at end deftypefun
-
- at deftypefun {const char *} xaccSplitGetAction (Split * @var{split})
-Return the Action field of @var{split}.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccSplitGetBalance (Split * @var{split})
-Return the balance of @var{split}'s parent Account up to and including
- at var{split}. See @ref{Accounts} for details.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccSplitGetClearedBalance (Split * @code{split})
-Return the cleared balance of @var{split}'s parent Account up to and
-including @var{split}. See @ref{Accounts} for details.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccSplitGetReconciledBalance (Split * @code{split})
-Return the reconciled balance of @var{split}'s parent Account up to and
-including @var{split}. See @ref{Accounts} for details.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccSplitGetShareBalance (Split * @var{split})
-Return the share balance of @var{split}'s parent Account up to and
-including @var{split}. See @ref{Accounts} for details.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccSplitGetShareClearedBalance (Split * @code{split})
-Return the share cleared balance of @var{split}'s parent Account up to
-and including @var{split}. See @ref{Accounts} for details.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccSplitGetShareReconciledBalance (Split * @code{split})
-Return the share reconciled balance of @var{split}'s parent Account up
-to and including @var{split}. See @ref{Accounts} for details.
- at end deftypefun
-
- at deftypefun {const char*} xaccSplitGetType (Split * @var{split})
-Return @var{split}'s type as a string. Currently, the possibilities are
-
- @table @code
- @item normal
- a normal split -- the default.
-
- @item stock-split
- a split representing a stock split. The value should be 0 and the
- share amount should represent the number of shares added/subtracted from
- the account as a result of the forward/reverse stock split.
- @end table
-
- at end deftypefun
-
-
- at node Split Setters, , Split Getters, Splits
- at subsection Split Setters
-
- at deftypefun void xaccSplitSetMemo (Split * @var{split}, const char * @var{memo})
-Set the memo field of @var{split} to @var{memo}.
- at end deftypefun
-
- at deftypefun void xaccSplitSetAction (Split * @var{split}, const char * @var{action})
-Set the action field of @var{split} to @var{memo}. The action field is
-an arbitrary string, but is intended to be conveniently limited to a
-menu of selections such as "Buy", "Sell", "Interest", etc.
- at end deftypefun
-
- at deftypefun void xaccSplitSetReconcile (Split * @var{split}, char @var{reconciled_flag})
-Set the reconciled flag of @var{split} to @var{reconciled_flag}. For the
-possible values and meanings of @var{reconciled_flag}, see @ref{Split Getters}.
- at end deftypefun
-
- at deftypefun void xaccSplitSetDateReconciledSecs (Split * @var{split}, time_t @var{time})
-Set the reconciliation date of @var{split} to @var{time}.
- at end deftypefun
-
- at deftypefun void xaccSplitSetDateReconciledTS (Split * @var{split}, Timespec * @var{ts})
-Set the reconciliation date of @var{split} to @var{ts}.
- at end deftypefun
-
- at deftypefun void xaccSplitSetShareAmount (Split * @var{split}, gnc_numeric amount)
-Set the share quantity of @var{split} to @var{amount}.
- at end deftypefun
-
- at deftypefun void xaccSplitSetSharePrice (Split * @var{split}, gnc_numeric @var{price})
-Set the share price of @var{split} to @var{price}.
- at end deftypefun
-
- at deftypefun void xaccSplitSetSharePriceAndAmount (Split * @var{split}, gnc_numeric @var{price}, gnc_numeric @var{amount})
-Set both the share price and share quantity of @var{split}. This routine
-is more efficent than calling @code{xaccSplitSetShareAmount} and
- at code{xaccSplitSetSharePrice} in succesion.
- at end deftypefun
-
- at deftypefun void xaccSplitSetValue (Split * @var{split}, gnc_numeric @var{value})
-Adjust the share quantity of @var{split} so that @var{split}'s value is
-equal to @var{value}.
- at end deftypefun
-
- at deftypefun void xaccSplitSetBaseValue (Split * @var{split}, gnc_numeric @var{value}, const char * @var{base_currency})
-Set either the share quantity or value of @var{split} depending upon
-whether @var{base_currency} is the security or current of @var{split}'s
-parent Account. @xref{Accounts}.
- at end deftypefun
-
-
- at node Transactions, Accounts, Splits, Engine
- at section Transactions
- at tindex Transaction
-
-A Transaction is the Engine abstraction of an accounting entry in a
-Journal. In accounting terms, a Transaction is a Journal Entry. As
-such, it contains the following pieces of information:
-
- at table @asis
-
- at item A list of Ledger Entries, or Splits
-The list of debits and credits which make up this Transaction. As in
-accounting, a Transaction is balanced when the sum of the debits equals
-the sum of the credits.
-
- at item The entry date
-The date the transaction was entered into GnuCash.
-
- at item The post date
-The date the transaction was posted. This is often the date the
-transaction was recorded by the bank, or the date the user initiated
-the transaction (i.e., wrote the check, made the ATM withdrawal).
-
- at item A transaction number field
-This field is intended to hold a transaction number, such as a
-check number or an ID assigned by a bank to an electronic transfer.
-
- at item A description
-A textual description of the transaction.
-
- at end table
-
-In addition to the above, Transactions contain a key-value pair frame.
-
-
- at subsection The Transaction Edit Cycle
-
-The Engine supports (and, in fact, requires) a 2-phase commit/rollback
-cycle for modifying Transactions and their constituent Splits. A Transaction
-must be opened for editing using @code{xaccTransBeginEdit()} before any of
-the following actions may be taken.
-
- at itemize
-
- at item
-Modifying any field of a Transaction.
-
- at item
-Modifying any Split belonging to the Transaction. That includes
-re-parenting a Split to a different Account or a different Transaction.
-In the case of re-parenting to a new Transaction, both Transactions must
-be opened for editing.
-
- at item
-Deleting any Split belonging to the Transaction.
-
- at item
-Adding a Split to the transaction.
-
- at item
-Deleting the Transaction.
-
- at end itemize
-
-After the desired changes have been made, they must either be committed
-using @code{xaccTransCommitEdit()} or rolled back using
- at code{xaccTransRollbackEdit()}. Rolling back a transaction will undo any
-changes which have been made to it or to its Splits since it was opened
-for editing.
-
-
- at menu
-* General Transaction API::
-* Transaction Getters::
-* Transaction Setters::
- at end menu
-
-
- at node General Transaction API, Transaction Getters, Transactions, Transactions
- at subsection General Transaction API
-
- at deftypefun {Transaction *} xaccMallocTransaction (void)
-Allocate, initialize, and return a new Transaction.
- at end deftypefun
-
- at deftypefun void xaccTransDestroy (Transaction * {trans})
-Remove all of the Splits from each of their accounts and free the memory
-associated with them. This routine must be followed by either an
- at code{xaccTransCommitEdit()} in which case the transaction memory will
-be freed, or by @code{xaccTransRollbackEdit()}, in which case all the
-original Splits are put back into place.
- at end deftypefun
-
- at deftypefun void xaccTransAppendSplit (Transaction * @var{trans}, Split * @var{split})
-Append @var{split} to the collection of Splits in @var{trans}. If the
-Split is already a part of another Transaction, it will be removed from
-that Transaction first.
- at end deftypefun
-
- at deftypefun void xaccTransBeginEdit (Transaction * @var{trans})
-This method must be called before any changes are made to @var{trans} or
-any of its component Splits. If this is not done, errors will result.
- at end deftypefun
-
- at deftypefun void xaccTransCommitEdit (Transaction * @var{trans})
-This method indicates that the changes to @var{trans} and its Splits are
-complete and should be made permanent. Note this routine may result in
-the deletion of the transaction, if the Transaction is "empty" (has no
-Splits) or if @code{xaccTransDestroy()} was called on the Transaction.
- at end deftypefun
-
- at deftypefun void xaccTransRollbackEdit (Transaction * @var{trans})
-Rejects all changes made to @var{trans} and its Splits, and sets
- at var{trans} back to where it was before the @code{xaccTransBeginEdit()}
-call. This includes restoring any deleted Splits, removing any added
-Splits, and undoing the effects of @code{xaccTransDestroy()}, as well
-as restoring share quantities, memos, descriptions, etc.
- at end deftypefun
-
- at deftypefun gboolean xaccTransIsOpen (Transaction * @var{trans})
-Return @code{TRUE} if @var{trans} is open for editing. Otherwise, it
-returns @code{FALSE}.
- at end deftypefun
-
- at deftypefun {const GUID *} xaccTransGetGUID (Transaction * @var{trans})
-Return the GUID of @var{trans}.
- at end deftypefun
-
- at deftypefun {Transaction *} xaccTransLookup (const GUID * @var{guid})
-Return the Transaction associated with @var{GUID}, or @code{NULL} if
-there is no such Transaction.
- at end deftypefun
-
- at deftypefun {kvp_value *} xaccTransGetSlot (Transaction * @var{trans}, const char * @var{key})
-Return the @code{kvp_value} associated with @var{key} in @var{trans}.
-If there is none, @code{NULL} is returned.
- at end deftypefun
-
- at deftypefun void xaccTransSetSlot (Split * @var{trans}, const char * @var{key}, const kvp_value * @var{value})
-Associate a copy of @var{value} with @var{key} in @var{trans}.
- at end deftypefun
-
-
- at node Transaction Getters, Transaction Setters, General Transaction API, Transactions
- at subsection Transaction Getters
-
- at deftypefun {Split *} xaccTransGetSplit (Transaction * @var{trans}, int @var{i})
-Return the @var{I}th Split of @var{trans}.
- at end deftypefun
-
- at deftypefun {GList *} xaccTransGetSplitList (Transaction * @var{trans})
-Return a @code{GList} of the Splits in @var{trans}. This list is owned
-by @var{trans} and should not be modified in any way!
- at end deftypefun
-
- at deftypefun {const char *} xaccTransGetNum (Transaction * @var{trans})
-Return the number field of @var{trans}.
- at end deftypefun
-
- at deftypefun {const char *} xaccTransGetDescription (Transaction * @var{trans})
-Return the description field of @var{trans}.
- at end deftypefun
-
- at deftypefun time_t xaccTransGetDate (Transaction * @var{trans})
-Return the post date of @var{trans} as a @code{time_t} value.
- at end deftypefun
-
- at deftypefun {long long} xaccTransGetDateL (Transaction * @var{trans})
-Return the post date of @var{trans} as a @code{long long} value.
- at end deftypefun
-
- at deftypefun void xaccTransGetDateTS (Transaction * @var{trans}, Timespec * @var{ts})
-Return the post date of @var{trans} in @var{ts}.
- at end deftypefun
-
- at deftypefun void xaccTransGetDateEnteredTS (Transaction * @var{trans}, Timespec * @var{ts})
-Return the entry date of @var{trans} in @var{ts}.
- at end deftypefun
-
- at deftypefun {char *} xaccTransGetDateStr (Transaction * @var{trans})
-Return a string representing the post date of @var{trans}, or NULL if
- at var{trans} is NULL. The string must be freed with @code{free()} after
-use.
- at end deftypefun
-
- at deftypefun int xaccTransCountSplits (Transaction * @var{trans})
-Return the number of Splits in @var{trans}.
- at end deftypefun
-
-
- at node Transaction Setters, , Transaction Getters, Transactions
- at subsection Transaction Setters
-
-Remember, before you modify a Transaction, you must open it for editing
-with @code{xaccTransBeginEdit}.
-
- at deftypefun void xaccTransSetDate (Transaction * @var{trans}, int @var{day}, int @var{mon}, int @var{year})
-Set the post date of @var{trans} with @var{day}, @var{month}, and @var{year}.
- at end deftypefun
-
- at deftypefun void xaccTransSetDateSecs (Transaction * @var{trans}, time_t @var{time})
-Set the post date of @var{trans} using a @code{time_t} value.
- at end deftypefun
-
- at deftypefun void xaccTransSetDateToday (Transaction * @var{trans})
-Set the post date of @var{trans} to the current time.
- at end deftypefun
-
- at deftypefun void xaccTransSetDateTS (Transaction * @var{trans}, const Timespec * @var{ts})
-Set the post date of @var{trans} from @var{ts}.
- at end deftypefun
-
- at deftypefun void xaccTransSetDateEnteredSecs (Transaction *trans, time_t time)
-Set the entry date of @var{trans} from a @code{time_t} value.
- at end deftypefun
-
- at deftypefun void xaccTransSetDateEnteredTS (Transaction * @var{trans}, const Timespec * @var{ts})
-Set the entry date of @var{trans} from @var{ts}.
- at end deftypefun
-
- at deftypefun void xaccTransSetNum (Transaction * @var{trans}, const char * @var{num})
-Set the number field of @var{trans} to @var{num}.
- at end deftypefun
-
- at deftypefun void xaccTransSetDescription (Transaction * @var{trans}, const char * @var{desc})
-Set the description field of @var{trans} to @var{desc}.
- at end deftypefun
-
-
- at node Accounts, Account Groups, Transactions, Engine
- at section Accounts
- at tindex Account
-
-An Account is the Engine abstraction of an, well, an account. Accounts
-contain the following pieces of information:
-
- at table @asis
-
- at item A list of Ledger Entries, or Splits
-The list of debits and credits which apply to the Account. The sum of
-all debits and credits is the account balance.
-
- at item A type
-An integer code identifying the type of account. The Account type
-determines whether the Account holds shares valued in a currency
-or not. It is also used by the GUI and reporting system to determine
-how debits & credits to the Account should be treated and displayed.
-
- at item A name
-The name of the Account.
-
- at item An account code
-A string that is intended to hold a unique user-selected identifier
-for the account. However, uniqueness of this field is not enforced.
-
- at item A description
-A textual description of the Account.
-
- at item A currency
-The commodity that Splits in the account are valued in, i.e., the
-denomination of the 'value' member of Splits in the account.
-
- at item A curreny SCU
-The SCU is the smallest convertible unit that the currency is
-traded in. This value overrides the default SCU of the currency.
-
- at item A security
-For Accounts which may contain shares (such as stock accounts),
-the denomination of the 'share quantity' member of Splits in
-the accounts. For accounts which do not contain shares, the
-security is blank, and the share quantities are denominated
-in the Account currency.
-
- at item A security SCU
-Analogous to the currency SCU, but for the security.
-
- at item A parent and child Account Group.
-The parent and child of an Account are Account Groups
-(@pxref{Account Groups}). Account Groups are used to
-connect Accounts together into an Account hierarchy.
-If the parent Account Group is not present, the Account
-is at the top level of the hierarchy. If the child
-Account Group is not present, the Account has no
-children.
-
- at end table
-
-In addition to the above, Accounts contain a key-value pair frame.
-
- at menu
-* Account Types::
-* General Account API::
-* Account Type API::
-* Account Getters::
-* Account Tax API::
- at end menu
-
-
- at node Account Types, General Account API, Accounts, Accounts
- at subsection Account Types
- at tindex GNCAccountType
-
-Account Types are defined by the @code{GNCAccountType} enumeration.
-Possible values are:
-
- @table @code
-
- @item BAD_TYPE, NO_TYPE
- Both of these values indicate an illegal Account type.
-
- @item BANK
- Denotes a savings or checking account held at a bank.
- Such an account is often interest bearing.
-
- @item CASH
- Denotes a shoe-box or pillowcase stuffed with cash. In other
- words, actual currency held by the user.
-
- @item CREDIT
- Denotes credit card accounts.
-
- @item ASSET
- Denotes a generic asset account.
-
- @item LIABILITY
- Denotes a generic liability account.
-
- @item STOCK
- A stock account containing stock shares.
-
- @item MUTUAL
- A mutual fund account containing fund shares.
-
- @item CURRENCY
- Denotes a currency trading account. In many ways, a currency trading
- account is like a stock trading account, where both quantities
- and prices are set. However, generally both currency and security
- are national currencies.
-
- @item INCOME
- Denotes an income account. The GnuCash financial model does not
- use 'categories'. Actual accounts are used instead.
-
- @item EXPENSE
- Denotes an expense account.
-
- @item EQUITY = 10,
- Denotes an equity account.
-
- @end table
-
-
- at node General Account API, Account Type API, Account Types, Accounts
- at subsection General Account API
-
- at deftypefun {Account *} xaccMallocAccount (void)
-Allocate and initialize an Account. The account must be
-destroyed by calling @code{xaccAccountBeginEdit} followed
-by @code{xaccAccountDestroy}.
- at end deftypefun
-
- at deftypefun void xaccAccountDestroy (Account * @var{account})
-Destroys @var{account} and frees all memory associated with
-it. This routine will also destroy the Account's children.
-You must call @code{xaccAccountBeginEdit} before calling
-this function.
- at end deftypefun
-
- at deftypefun void xaccAccountBeginEdit (Account * @var{account})
-This routine, together with @code{xaccAccountCommitEdit},
-provide a two-phase-commit wrapper for account updates
-much in the same way as @var{xaccTransBeginEdit} and
- at var{xaccTransCommitEdit} do for Transactions.
- at end deftypefun
-
- at deftypefun void xaccAccountCommitEdit (Account * @var{account})
-The counterpart to @var{xaccAccountBeginEdit}.
- at end deftypefun
-
- at deftypefun {Account *} xaccCloneAccountSimple (const Account * @var{from})
-Return a 'copy' of @var{from} that is identical in the type, name, code,
-description, kvp data, and currency. All other fields are the same as an
-account returned by @code{xaccMallocAccount}.
- at end deftypefun
-
- at deftypefun {const GUID *} xaccAccountGetGUID (Account * @var{account})
-Return the globally unique id associated with @var{account}.
- at end deftypefun
-
- at deftypefun {Account *} xaccAccountLookup (const GUID * @var{guid})
-Return the Account associated with @var{guid}, or NULL if there is
-no such Account.
- at end deftypefun
-
- at deftypefun {kvp_frame *} xaccAccountGetSlots (Account * @var{account})
-Return the @code{kvp_frame} associated with @var{account}. User code
-may modify this @code{kvp_frame}, but must not destroy it.
- at end deftypefun
-
- at deftypefun void xaccAccountSetSlots_nc (Account * @var{account}, kvp_frame * @var{frame})
-Set the @code{kvp_frame} associated wih @var{account}. After the call,
- at var{frame} is owned by @var{account}, so don't destroy it.
- at end deftypefun
-
-
- at node Account Type API, Account Getters, General Account API, Accounts
- at subsection Account Type API
-
- at deftypefun {const char *} xaccAccountGetTypeStr (GNCAccountType @var{type})
-Return a string corresponding to the given Account type suitable for
-display by a GUI. The string is translated with gettext according to
-the current locale.
- at end deftypefun
-
- at deftypefun {char *} xaccAccountTypeEnumAsString (GNCAccountType @var{type})
-Return a string corresponding to the given Account type. The string
-is not translated and is independent of the current locale.
- at end deftypefun
-
- at deftypefun gboolean xaccAccountStringToType (const char * @var{str}, GNCAccountType * @var{type})
-Converts a string of the form returned by @code{xaccAccountTypeEnumAsString}
-to a type, return in @var{type}. Returns true if the string corresponds
-to an actual type.
- at end deftypefun
-
- at deftypefun GNCAccountType xaccAccountStringToEnum (const char * @var{str})
-Similar to @code{xaccAccountStringToEnum}, but returns the type. If
- at var{str} does not correspond to any valid type, @code{BAD_TYPE} is
-returned.
- at end deftypefun
-
- at deftypefun gboolean xaccAccountTypesCompatible (GNCAccountType @var{parent_type}, GNCAccountType @var{child_type})
-Returns TRUE if accounts of type @var{parent_type} can have child accounts
-of type @var{child_type}. This compatibility is not enforced by the
-engine, but one day it may be!
- at end deftypefun
-
-
- at node Account Getters, Account Tax API, Account Type API, Accounts
- at subsection Account Getters
-
- at deftypefun GNCAccountType xaccAccountGetType (Account * @var{account})
-Return the type of @var{account}.
- at end deftypefun
-
- at deftypefun {const char *} xaccAccountGetName (Account * @var{account})
-Return the name of @var{account}.
- at end deftypefun
-
- at deftypefun {const char *} xaccAccountGetCode (Account * @var{account})
-Return the code of @var{account}.
- at end deftypefun
-
- at deftypefun {const char *} xaccAccountGetDescription (Account * @var{account})
-Return the description of @var{account}.
- at end deftypefun
-
- at deftypefun {const char *} xaccAccountGetNotes (Account * @var{account})
-Return the notes of @var{account}.
- at end deftypefun
-
- at deftypefun {gnc_commodity *} xaccAccountGetCurrency (Account * @var{account})
-Return the currency of @var{account}.
- at end deftypefun
-
- at deftypefun int xaccAccountGetCurrencySCU (Account * @var{account})
-Return the SCU (smallest convertible unit) of @var{account}'s
-currency.
- at end deftypefun
-
- at deftypefun {gnc_commodity *} xaccAccountGetSecurity (Account * @var{account})
-Return the security of @var{account}. For accounts without shares, this
-field will be @code{NULL}.
- at end deftypefun
-
- at deftypefun int xaccAccountGetSecuritySCU (Account * @var{account})
-Return the SCU (smallest convertible unit) of @var{account}'s
-security.
- at end deftypefun
-
- at deftypefun {gnc_commodity *} xaccAccountGetEffectiveSecurity (Account * @var{account})
-Get the `effective' security of the account. If the account has a non-NULL
-security field, that field will be returned. Otherwise, the currency will
-be returned.
- at end deftypefun
-
- at deftypefun {AccountGroup *} xaccAccountGetChildren (Account * @var{account})
-Return the child group of @var{account}. The child group may be @code{NULL},
-indicating @var{account} has no children.
- at end deftypefun
-
- at deftypefun {AccountGroup *} xaccAccountGetParent (Account * @var{account})
-Return the parent Group of @var{account}. The parent may be @code{NULL},
-indicating @var{account} is a top-level Account. However, even if the
-parent is not @code{NULL}, the account may still be top-level if the
-parent Group has no parent Account.
- at end deftypefun
-
- at deftypefun {Account *} xaccAccountGetParentAccount (Account * @var{account})
-Similar to @code{xaccAccountGetParent}, but returns the parent Account
-of the parent Group if the parent Group exists. Otherwise, returns
- at code{NULL}.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccAccountGetBalance (Account * @var{account})
-Return the balance of @var{account}, which is also the balance of the
-last Split in @var{account}. If there are no Splits, the balance is
-zero. The balance is denominated in the Account currency.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccAccountGetClearedBalance (Account * @var{account})
-Return the cleared balance of @var{account}. The cleared balance is the
-balance of all Splits in @var{account} which are either cleared or
-reconciled or frozen. The cleared balance is denominated in the Account
-currency.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccAccountGetReconciledBalance (Account * @var{account})
-Return the reconciled balance of @var{account}. The reconciled balance
-is the balance of all Splits in @var{account} which are reconciled or
-frozen. The reconciled balance is denominated in the Account currency.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccAccountGetShareBalance (Account *account)
-Return the share balance of @var{account}, which is also the share
-balance of the last Split in @var{account}. If there are no Splits, the
-balance is zero. The balance is denominated in the Account security, if
-the Account security exits; otherwise the share balance is denominated
-in the Account currency.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccAccountGetShareClearedBalance (Account * @var{account})
-Return the cleared share balance of @var{account}. The cleared share
-balance is the share balance of all Splits in @var{account} which are
-either cleared or reconciled or frozen. The cleared share balance is
-denominated as the share balance.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccAccountGetShareReconciledBalance (Account * @var{account})
-Return the reconciled share balance of @var{account}. The reconciled
-share balance is the share balance of all Splits in @var{account} which
-are reconciled or frozen. The reconciled sharea balance is denominated
-as the share balance.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccAccountGetBalanceAsOfDate (Account * @var{account}, time_t @var{date})
-Return the balance of @var{account} including all Splits whose parent
-Transactions have posted dates on or before @var{date}.
- at end deftypefun
-
- at deftypefun gnc_numeric xaccAccountGetShareBalanceAsOfDate (Account * @var{account}, time_t @var{date})
-Return the share balance of @var{account} including all Splits whose
-parent Transactions have posted dates on or before @var{date}.
- at end deftypefun
-
- at deftypefun {GList *} xaccAccountGetSplitList (Account * @var{account})
-Return a @code{GList} of the Splits in @var{account}. This list must
-not be modified in any way.
- at end deftypefun
-
- at deftypefun {char *} xaccAccountGetFullName (Account * @var{account}, const char @var{separator})
-Returns the fully qualified name of @var{account} using the given
-separator character. The name must be g_freed after use. The fully
-qualified name of an account is the concatenation of the names of the
-account and all its ancestor accounts starting with the topmost account
-and ending with the given account. Each name is separated by the given
-character.
- at end deftypefun
-
-
- at node Account Tax API, , Account Getters, Accounts
- at subsection Account Tax API
-
-This set of API calls is related to tax information. All accounts have a
-tax-related boolean flag that can be set or unset. There is an
-additional set of API calls related to United States taxes that have
-`US' in the function call names. Future API calls that are specific to
-other countries should include the appropriate 2-letter country code in
-the function names.
-
- at deftypefun gboolean xaccAccountGetTaxRelated (Account * @var{account})
-Return the tax-related flag of @var{account}.
- at end deftypefun
-
- at deftypefun void xaccAccountSetTaxRelated (Account * @var{account}, gboolean @var{tax_related})
-Set the tax-related flag of @var{account}.
- at end deftypefun
-
- at deftypefun {const char *} xaccAccountGetTaxUSCode (Account * @var{account})
-Get the US-specific tax code associated with @var{account}, or
- at code{NULL} if there is none. These codes are internal to GnuCash
-and currently defined in @file{src/scm/report/txf-export.scm}.
- at end deftypefun
-
- at deftypefun void xaccAccountSetTaxUSCode (Account * @var{account}, const char * @var{code})
-Set the US-specific tax code associated with @var{account}.
- at end deftypefun
-
- at deftypefun {const char *} xaccAccountGetTaxUSPayerNameSource (Account * @var{account})
-Get the payer name source associated with @var{account}. See
- at file{src/scm/repot/taxtxf.scm} for details.
- at end deftypefun
-
- at deftypefun void xaccAccountSetTaxUSPayerNameSource (Account * @var{account}, const char * @var{source})
-Set the payer name source associated with @var{account}.
- at end deftypefun
-
-
- at node Account Groups, GNCBooks, Accounts, Engine
- at section Account Groups
- at tindex AccountGroup
-
-Account Groups are used by the Engine to connect Accounts
-together into an Account hierarchy. Account Groups do not
-correspond to any accounting concept -- they are specific
-to the GnuCash engine. Account Groups contain the following
-pieces of information:
-
- at table @asis
-
- at item A list of Accounts
-The list Accounts in the Group.
-
- at item A not-saved flag
-Indicates whether any information in the hierarchy
-rooted at the Group needs to be saved. That includes
-Accounts, Splits, and Transactions.
-
- at end table
-
-Account Groups do not have key-value frames or GUIDs.
-
- at menu
-* General Account Group API::
-* Account Group Account API::
- at end menu
-
- at node General Account Group API, Account Group Account API, Account Groups, Account Groups
- at subsection General Account Group API
-
- at deftypefun {AccountGroup *} xaccMallocAccountGroup (void)
-Return a newly-allocated & initialized Account Group.
-The Group must be freed with @code{xaccFreeAccountGroup}.
- at end deftypefun
-
- at deftypefun void xaccFreeAccountGroup (AccountGroup * @var{account_group})
-Free the given Group and all its resources, including the Accounts.
- at end deftypefun
-
- at deftypefun void xaccAccountGroupCommitEdit (AccountGroup * @var{grp})
-Recursively call @code{xaccAccountCommitEdit} on all child accounts
-and their children.
- at end deftypefun
-
- at deftypefun void xaccGroupConcatGroup (AccountGroup * @var{to}, AccountGroup * @var{from})
-Move all accounts in @var{from} to @var{to}. After this function
-returns, @var{from} will have been destroyed.
- at end deftypefun
-
- at deftypefun void xaccGroupMergeAccounts (AccountGroup * @var{grp})
-Merge all accounts in @var{grp} that have the same name and description.
-The semantics of this function are rather complex. Consult the
-implementation before use!
- at end deftypefun
-
- at deftypefun gboolean xaccGroupNotSaved (AccountGroup * @var{grp})
-Return true if @var{grp} has changes which have not been saved.
- at end deftypefun
-
- at deftypefun void xaccGroupMarkSaved (AccountGroup * @var{grp})
-Mark @var{grp} and all its children as saved.
- at end deftypefun
-
- at deftypefun void xaccGroupMarkNotSaved (AccountGroup * @var{grp})
-Mark @var{grp} as not saved.
- at end deftypefun
-
- at deftypefun void xaccGroupMarkDoFree (AccountGroup * @var{grp})
-Mark all accounts in @var{grp} as slated for destruction. This will
-improve the efficiency of destroying a large account hierarchy.
- at end deftypefun
-
-
- at node Account Group Account API, , General Account Group API, Account Groups
- at subsection Account Group Account API
-
- at deftypefun void xaccGroupRemoveAccount (AccountGroup * @var{grp}, Account * @var{account})
-Remove @var{account} from @var{grp}. If @var{account} is not in
- at var{grp}, the function will return without performing any action.
-In no case will @var{account} be destroyed or modified.
- at end deftypefun
-
- at deftypefun void xaccAccountRemoveGroup (Account * @var{acc})
-Remove @var{acc}'s child group. The child group is not otherwise
-modified or destroyed.
- at end deftypefun
-
- at deftypefun void xaccGroupInsertAccount (AccountGroup * @var{grp}, Account * @var{acc})
-Add @var{acc} to @var{grp}. If @var{acc} is in another Group, it will be
-removed first.
- at end deftypefun
-
- at deftypefun void xaccAccountInsertSubAccount (Account * @var{parent}, Account * @var{child})
-Like @code{xaccGroupInsertAccount}, but uses a parent Account instead
-of a parent group. If @var{parent} does not have a child Group, one
-will be created.
- at end deftypefun
-
- at deftypefun int xaccGroupGetNumSubAccounts (AccountGroup * @var{grp})
-Return the total number of Accounts in the hierarchy rooted at @var{grp}.
- at end deftypefun
-
- at deftypefun int xaccGroupGetNumAccounts (AccountGroup * @var{grp})
-Return the number of accounts in @var{grp}. This count does not
-include Accounts lower in the hierarchy.
- at end deftypefun
-
- at deftypefun int xaccGroupGetDepth (AccountGroup * @var{grp})
-Returns the length of the longest tree branch in the hierarchy
-rooted at @var{grp}. Each link between an Account and its
-(non-null) children counts as one unit of length.
- at end deftypefun
-
- at deftypefun {Account *} xaccGroupGetAccount (AccountGroup * @var{group}, int @var{index})
-Return the @var{index}th Account in @var{group}, starting at zero.
-If @var{index} is out of range, @code{NULL} is returned.
- at end deftypefun
-
- at deftypefun {GList *} xaccGroupGetSubAccounts (AccountGroup * @var{grp})
-Return a list of the Accounts, including sub-Accounts, in @var{grp}. The
-returned list should be freed with @code{g_list_free} when no longer
-needed.
- at end deftypefun
-
- at deftypefun {GList *} xaccGroupGetAccountList (AccountGroup * @var{grp})
-Return a list of the immediate children of @var{grp}. The returned list
-should not be freed or modified in any way.
- at end deftypefun
-
-
- at node GNCBooks, Scrub, Account Groups, Engine
- at section GNCBooks
- at tindex GNCBook
-
-The @dfn{GNCBook} interface encapsulates all the information about a
-GnuCash dataset, including the methods used to read and write the
-dataset to datastores. This class provides several important services:
-
- at itemize
-
- at item
-Prevents multiple users from editing the same file at the same time,
-thus avoiding lost data due to race conditions. Thus an 'open book'
-implies that the associated file is locked.
-
- at item
-Provides a search path for the file to be edited. This should simplify
-install & maintenance problems for users who may not have a good grasp
-of what a file system is, or where they want to keep their data files.
-
- at end itemize
-
-The current implementation assumes the use of files and file locks;
-however, the API was designed to be general enough to allow the use
-of generic URL's, and/or implementation on top of SQL or other
-database/persistant object technology.
-
- at menu
-* GNCBook API::
- at end menu
-
-
- at node GNCBook API, , GNCBooks, GNCBooks
- at subsection GNCBook API
-
- at deftypefun {GNCBook *} gnc_book_new (void)
-Allocate, initialize, and return a new GNCBook. The new book will contain
-a newly allocated AccountGroup.
- at end deftypefun
-
- at deftypefun void gnc_book_destroy (GNCBook * @var{book})
-End any editing session associated with @var{book}, and free all
-memory associated with it.
- at end deftypefun
-
- at deftypefun gboolean gnc_book_begin (GNCBook * @var{book}, const char * @var{book_id}, gboolean ignore_lock, gboolean create_if_nonexistent)
-Begins a new book editing sesssion. It takes as an argument the book id.
-The book id must be a string in the form of a URI/URL. In the current
-implementation, only one type of URI is supported, and that is the file
-URI: anything of the form @url{file:/home/somewhere/somedir/file.xac}
-The path part must be a valid path. The file-part must be a valid
-GnuCash data file. Paths may be relative or absolute. If the path is
-relative; that is, if the argument is @url{file:somefile.xac} then a
-sequence of search paths are checked for a file of this name.
-
-The 'ignore_lock' argument, if set to TRUE, will cause this routine to
-ignore any file locks that it finds. If set to FALSE, then file locks
-will be tested and obeyed.
-
-If the file exists, can be opened and read, and a lock can be obtained
-then a lock will be obtained and the function returns TRUE.
-
-If the file/database doesn't exist, and the create_if_nonexistent flag
-is set to TRUE, then the database is created.
-
-Otherwise the function returns FALSE.
- at end deftypefun
-
- at deftypefun gboolean gnc_book_load (GNCBook * @var{book})
-Load the data associated with the book. The function returns TRUE on
-success.
- at end deftypefun
-
- at deftypefun GNCBackendError gnc_book_get_error (GNCBook * @var{book})
-Obtain the reason for a failure. Standard errno values are used. Calling
-this routine resets the error value. This routine allows an
-implementation of multiple error values, e.g. in a stack, where this
-routine pops the top value. The current implementation has a stack that
-is one-deep.
-
-Some important error values:
-
- at table @code
-
- at item EINVAL
-bad argument
-
- at item ETXTBSY
-book id is in use; it's locked by someone else
-
- at item ENOSYS
-unsupported URI type
-
- at item ERANGE
-file path too long
-
- at item ENOLCK
-book not open when @code{gnc_book_save()} was called.
-
- at end table
- at end deftypefun
-
- at deftypefun {const char *} gnc_book_get_error_message (GNCBook * @var{book})
-Return a string describing the reason for the current error. Calling
-this routine resets the error value.
- at end deftypefun
-
- at deftypefun GNCBackendError gnc_book_pop_error (GNCBook * @var{book})
-Same as @code{gnc_book_get_error}, but the error value is reset
-in @var{book}.
- at end deftypefun
-
- at deftypefun {AccountGroup *} gnc_book_get_group (GNCBook * @var{book})
-Return the current top-level account group.
- at end deftypefun
-
- at deftypefun void gnc_book_set_group (GNCBook * @var{book}, AccountGroup * @var{topgroup})
-Set the topgroup to a new value.
- at end deftypefun
-
- at deftypefun {const char *} gnc_book_get_file_path (GNCBook * @var{book})
-Return the fully-qualified file path for the book. That is, if a
-relative or partial filename was for the book, then it had to have been
-fully resolved to open the book. This routine returns the result of this
-resolution.
- at end deftypefun
-
- at deftypefun gboolean gnc_book_save_may_clobber_data (GNCBook * @var{book})
-Return TRUE if saving the book would overwrite other information.
- at end deftypefun
-
- at deftypefun void gnc_book_save (GNCBook * @var{book})
-Commit all changes that have been made to the book.
- at end deftypefun
-
- at deftypefun void gnc_book_end (GNCBook * @var{book})
-Release the session lock. It will @emph{not} save the account group to
-a file. Thus, this method acts as an "abort" or "rollback" primitive.
- at end deftypefun
-
-
- at node Scrub, , GNCBooks, Engine
- at section Scrub
Copied: gnucash/trunk/src/doc/design/fdl.texi (from rev 23343, gnucash/trunk/src/doc/design/fdl.texinfo)
===================================================================
--- gnucash/trunk/src/doc/design/fdl.texi (rev 0)
+++ gnucash/trunk/src/doc/design/fdl.texi 2013-10-28 01:02:53 UTC (rev 23344)
@@ -0,0 +1,384 @@
+ at node GNU Free Documentation License, Introduction, Top, Top
+ at unnumbered GNU Free Documentation License
+
+ at c This file is intended to be included in another file.
+
+ at center Version 1.1, March 2000
+
+ at display
+Copyright (C) 2000 Free Software Foundation, Inc.
+51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+ at end display
+
+ at unnumberedsec Preamble
+
+The purpose of this License is to make a manual, textbook, or other
+written document ``free'' in the sense of freedom: to assure everyone
+the effective freedom to copy and redistribute it, with or without
+modifying it, either commercially or noncommercially. Secondarily,
+this License preserves for the author and publisher a way to get
+credit for their work, while not being considered responsible for
+modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+ at unnumberedsec APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work that contains a
+notice placed by the copyright holder saying it can be distributed
+under the terms of this License. The ``Document'', below, refers to any
+such manual or work. Any member of the public is a licensee, and is
+addressed as ``you''.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (For example, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, whose contents can be viewed and edited directly and
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup has been designed to thwart or discourage
+subsequent modification by readers is not Transparent. A copy that is
+not ``Transparent" is called "Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, LaTeX input format, SGML
+or XML using a publicly available DTD, and standard-conforming simple
+HTML designed for human modification. Opaque formats include
+PostScript, PDF, proprietary formats that can be read and edited only
+by proprietary word processors, SGML or XML for which the DTD and/or
+processing tools are not generally available, and the
+machine-generated HTML produced by some word processors for output
+purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+ at unnumberedsec VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+ at unnumberedsec COPYING IN QUANTITY
+
+If you publish printed copies of the Document numbering more than 100,
+and the Document's license notice requires Cover Texts, you must enclose
+the copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a publicly-accessible computer-network location containing a complete
+Transparent copy of the Document, free of added material, which the
+general network-using public has access to download anonymously at no
+charge using public-standard network protocols. If you use the latter
+option, you must take reasonably prudent steps, when you begin
+distribution of Opaque copies in quantity, to ensure that this
+Transparent copy will remain thus accessible at the stated location
+until at least one year after the last time you distribute an Opaque
+copy (directly or through your agents or retailers) of that edition to
+the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+ at unnumberedsec MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+ at enumerate A
+ at item
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
+ at item
+ List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has less than five).
+
+ at item
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+ at item
+ Preserve all the copyright notices of the Document.
+
+ at item
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+ at item
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
+ at item
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
+ at item
+Include an unaltered copy of this License.
+
+ at item
+Preserve the section entitled ``History'', and its title, and add to
+it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
+ at item
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
+ at item
+In any section entitled ``Acknowledgements" or "Dedications'',
+preserve the section's title, and preserve in the section all the
+substance and tone of each of the contributor acknowledgements
+and/or dedications given therein.
+
+ at item
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
+ at item
+Delete any section entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
+ at item
+Do not retitle any existing section as ``Endorsements''
+or to conflict in title with any Invariant Section.
+ at end enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties--for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+ at unnumberedsec COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections entitled ``History''
+in the various original documents, forming one section entitled
+``History"; likewise combine any sections entitled "Acknowledgements'',
+and any sections entitled ``Dedications''. You must delete all sections
+entitled ``Endorsements.''
+
+ at unnumberedsec COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+ at unnumberedsec AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, does not as a whole count as a Modified Version
+of the Document, provided no compilation copyright is claimed for the
+compilation. Such a compilation is called an ``aggregate'', and this
+License does not apply to the other self-contained works thus compiled
+with the Document, on account of their being thus compiled, if they
+are not themselves derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one quarter
+of the entire aggregate, the Document's Cover Texts may be placed on
+covers that surround only the Document within the aggregate.
+Otherwise they must appear on covers around the whole aggregate.
+
+ at unnumberedsec TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License provided that you also include the
+original English version of this License. In case of a disagreement
+between the translation and the original English version of this
+License, the original English version will prevail.
+
+ at unnumberedsec TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+ at unnumberedsec FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+http://www.gnu.org/copyleft/.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
+
+
+
+ at unnumberedsec ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+ at display
+Copyright (c) YEAR YOUR NAME.
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1
+or any later version published by the Free Software Foundation;
+with the Invariant Sections being LIST THEIR TITLES, with the
+Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+A copy of the license is included in the section entitled "GNU
+Free Documentation License".
+ at end display
+
+If you have no Invariant Sections, write ``with no Invariant Sections''
+instead of saying which ones are invariant. If you have no
+Front-Cover Texts, write ``no Front-Cover Texts'' instead of
+``Front-Cover Texts being LIST''; likewise for Back-Cover Texts.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+ at c @bye
Deleted: gnucash/trunk/src/doc/design/fdl.texinfo
===================================================================
--- gnucash/trunk/src/doc/design/fdl.texinfo 2013-10-27 21:57:42 UTC (rev 23343)
+++ gnucash/trunk/src/doc/design/fdl.texinfo 2013-10-28 01:02:53 UTC (rev 23344)
@@ -1,384 +0,0 @@
- at node GNU Free Documentation License, Introduction, Top, Top
- at unnumbered GNU Free Documentation License
-
- at c This file is intended to be included in another file.
-
- at center Version 1.1, March 2000
-
- at display
-Copyright (C) 2000 Free Software Foundation, Inc.
-51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
-Everyone is permitted to copy and distribute verbatim copies
-of this license document, but changing it is not allowed.
- at end display
-
- at unnumberedsec Preamble
-
-The purpose of this License is to make a manual, textbook, or other
-written document ``free'' in the sense of freedom: to assure everyone
-the effective freedom to copy and redistribute it, with or without
-modifying it, either commercially or noncommercially. Secondarily,
-this License preserves for the author and publisher a way to get
-credit for their work, while not being considered responsible for
-modifications made by others.
-
-This License is a kind of ``copyleft'', which means that derivative
-works of the document must themselves be free in the same sense. It
-complements the GNU General Public License, which is a copyleft
-license designed for free software.
-
-We have designed this License in order to use it for manuals for free
-software, because free software needs free documentation: a free
-program should come with manuals providing the same freedoms that the
-software does. But this License is not limited to software manuals;
-it can be used for any textual work, regardless of subject matter or
-whether it is published as a printed book. We recommend this License
-principally for works whose purpose is instruction or reference.
-
- at unnumberedsec APPLICABILITY AND DEFINITIONS
-
-This License applies to any manual or other work that contains a
-notice placed by the copyright holder saying it can be distributed
-under the terms of this License. The ``Document'', below, refers to any
-such manual or work. Any member of the public is a licensee, and is
-addressed as ``you''.
-
-A ``Modified Version'' of the Document means any work containing the
-Document or a portion of it, either copied verbatim, or with
-modifications and/or translated into another language.
-
-A ``Secondary Section'' is a named appendix or a front-matter section of
-the Document that deals exclusively with the relationship of the
-publishers or authors of the Document to the Document's overall subject
-(or to related matters) and contains nothing that could fall directly
-within that overall subject. (For example, if the Document is in part a
-textbook of mathematics, a Secondary Section may not explain any
-mathematics.) The relationship could be a matter of historical
-connection with the subject or with related matters, or of legal,
-commercial, philosophical, ethical or political position regarding
-them.
-
-The ``Invariant Sections'' are certain Secondary Sections whose titles
-are designated, as being those of Invariant Sections, in the notice
-that says that the Document is released under this License.
-
-The ``Cover Texts'' are certain short passages of text that are listed,
-as Front-Cover Texts or Back-Cover Texts, in the notice that says that
-the Document is released under this License.
-
-A ``Transparent'' copy of the Document means a machine-readable copy,
-represented in a format whose specification is available to the
-general public, whose contents can be viewed and edited directly and
-straightforwardly with generic text editors or (for images composed of
-pixels) generic paint programs or (for drawings) some widely available
-drawing editor, and that is suitable for input to text formatters or
-for automatic translation to a variety of formats suitable for input
-to text formatters. A copy made in an otherwise Transparent file
-format whose markup has been designed to thwart or discourage
-subsequent modification by readers is not Transparent. A copy that is
-not ``Transparent" is called "Opaque''.
-
-Examples of suitable formats for Transparent copies include plain
-ASCII without markup, Texinfo input format, LaTeX input format, SGML
-or XML using a publicly available DTD, and standard-conforming simple
-HTML designed for human modification. Opaque formats include
-PostScript, PDF, proprietary formats that can be read and edited only
-by proprietary word processors, SGML or XML for which the DTD and/or
-processing tools are not generally available, and the
-machine-generated HTML produced by some word processors for output
-purposes only.
-
-The ``Title Page'' means, for a printed book, the title page itself,
-plus such following pages as are needed to hold, legibly, the material
-this License requires to appear in the title page. For works in
-formats which do not have any title page as such, ``Title Page'' means
-the text near the most prominent appearance of the work's title,
-preceding the beginning of the body of the text.
-
- at unnumberedsec VERBATIM COPYING
-
-You may copy and distribute the Document in any medium, either
-commercially or noncommercially, provided that this License, the
-copyright notices, and the license notice saying this License applies
-to the Document are reproduced in all copies, and that you add no other
-conditions whatsoever to those of this License. You may not use
-technical measures to obstruct or control the reading or further
-copying of the copies you make or distribute. However, you may accept
-compensation in exchange for copies. If you distribute a large enough
-number of copies you must also follow the conditions in section 3.
-
-You may also lend copies, under the same conditions stated above, and
-you may publicly display copies.
-
- at unnumberedsec COPYING IN QUANTITY
-
-If you publish printed copies of the Document numbering more than 100,
-and the Document's license notice requires Cover Texts, you must enclose
-the copies in covers that carry, clearly and legibly, all these Cover
-Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
-the back cover. Both covers must also clearly and legibly identify
-you as the publisher of these copies. The front cover must present
-the full title with all words of the title equally prominent and
-visible. You may add other material on the covers in addition.
-Copying with changes limited to the covers, as long as they preserve
-the title of the Document and satisfy these conditions, can be treated
-as verbatim copying in other respects.
-
-If the required texts for either cover are too voluminous to fit
-legibly, you should put the first ones listed (as many as fit
-reasonably) on the actual cover, and continue the rest onto adjacent
-pages.
-
-If you publish or distribute Opaque copies of the Document numbering
-more than 100, you must either include a machine-readable Transparent
-copy along with each Opaque copy, or state in or with each Opaque copy
-a publicly-accessible computer-network location containing a complete
-Transparent copy of the Document, free of added material, which the
-general network-using public has access to download anonymously at no
-charge using public-standard network protocols. If you use the latter
-option, you must take reasonably prudent steps, when you begin
-distribution of Opaque copies in quantity, to ensure that this
-Transparent copy will remain thus accessible at the stated location
-until at least one year after the last time you distribute an Opaque
-copy (directly or through your agents or retailers) of that edition to
-the public.
-
-It is requested, but not required, that you contact the authors of the
-Document well before redistributing any large number of copies, to give
-them a chance to provide you with an updated version of the Document.
-
- at unnumberedsec MODIFICATIONS
-
-You may copy and distribute a Modified Version of the Document under
-the conditions of sections 2 and 3 above, provided that you release
-the Modified Version under precisely this License, with the Modified
-Version filling the role of the Document, thus licensing distribution
-and modification of the Modified Version to whoever possesses a copy
-of it. In addition, you must do these things in the Modified Version:
-
- at enumerate A
- at item
-Use in the Title Page (and on the covers, if any) a title distinct
-from that of the Document, and from those of previous versions
-(which should, if there were any, be listed in the History section
-of the Document). You may use the same title as a previous version
-if the original publisher of that version gives permission.
-
- at item
- List on the Title Page, as authors, one or more persons or entities
-responsible for authorship of the modifications in the Modified
-Version, together with at least five of the principal authors of the
-Document (all of its principal authors, if it has less than five).
-
- at item
-State on the Title page the name of the publisher of the
-Modified Version, as the publisher.
-
- at item
- Preserve all the copyright notices of the Document.
-
- at item
-Add an appropriate copyright notice for your modifications
-adjacent to the other copyright notices.
-
- at item
-Include, immediately after the copyright notices, a license notice
-giving the public permission to use the Modified Version under the
-terms of this License, in the form shown in the Addendum below.
-
- at item
-Preserve in that license notice the full lists of Invariant Sections
-and required Cover Texts given in the Document's license notice.
-
- at item
-Include an unaltered copy of this License.
-
- at item
-Preserve the section entitled ``History'', and its title, and add to
-it an item stating at least the title, year, new authors, and
-publisher of the Modified Version as given on the Title Page. If
-there is no section entitled ``History'' in the Document, create one
-stating the title, year, authors, and publisher of the Document as
-given on its Title Page, then add an item describing the Modified
-Version as stated in the previous sentence.
-
- at item
-Preserve the network location, if any, given in the Document for
-public access to a Transparent copy of the Document, and likewise
-the network locations given in the Document for previous versions
-it was based on. These may be placed in the ``History'' section.
-You may omit a network location for a work that was published at
-least four years before the Document itself, or if the original
-publisher of the version it refers to gives permission.
-
- at item
-In any section entitled ``Acknowledgements" or "Dedications'',
-preserve the section's title, and preserve in the section all the
-substance and tone of each of the contributor acknowledgements
-and/or dedications given therein.
-
- at item
-Preserve all the Invariant Sections of the Document,
-unaltered in their text and in their titles. Section numbers
-or the equivalent are not considered part of the section titles.
-
- at item
-Delete any section entitled ``Endorsements''. Such a section
-may not be included in the Modified Version.
-
- at item
-Do not retitle any existing section as ``Endorsements''
-or to conflict in title with any Invariant Section.
- at end enumerate
-
-If the Modified Version includes new front-matter sections or
-appendices that qualify as Secondary Sections and contain no material
-copied from the Document, you may at your option designate some or all
-of these sections as invariant. To do this, add their titles to the
-list of Invariant Sections in the Modified Version's license notice.
-These titles must be distinct from any other section titles.
-
-You may add a section entitled ``Endorsements'', provided it contains
-nothing but endorsements of your Modified Version by various
-parties--for example, statements of peer review or that the text has
-been approved by an organization as the authoritative definition of a
-standard.
-
-You may add a passage of up to five words as a Front-Cover Text, and a
-passage of up to 25 words as a Back-Cover Text, to the end of the list
-of Cover Texts in the Modified Version. Only one passage of
-Front-Cover Text and one of Back-Cover Text may be added by (or
-through arrangements made by) any one entity. If the Document already
-includes a cover text for the same cover, previously added by you or
-by arrangement made by the same entity you are acting on behalf of,
-you may not add another; but you may replace the old one, on explicit
-permission from the previous publisher that added the old one.
-
-The author(s) and publisher(s) of the Document do not by this License
-give permission to use their names for publicity for or to assert or
-imply endorsement of any Modified Version.
-
- at unnumberedsec COMBINING DOCUMENTS
-
-You may combine the Document with other documents released under this
-License, under the terms defined in section 4 above for modified
-versions, provided that you include in the combination all of the
-Invariant Sections of all of the original documents, unmodified, and
-list them all as Invariant Sections of your combined work in its
-license notice.
-
-The combined work need only contain one copy of this License, and
-multiple identical Invariant Sections may be replaced with a single
-copy. If there are multiple Invariant Sections with the same name but
-different contents, make the title of each such section unique by
-adding at the end of it, in parentheses, the name of the original
-author or publisher of that section if known, or else a unique number.
-Make the same adjustment to the section titles in the list of
-Invariant Sections in the license notice of the combined work.
-
-In the combination, you must combine any sections entitled ``History''
-in the various original documents, forming one section entitled
-``History"; likewise combine any sections entitled "Acknowledgements'',
-and any sections entitled ``Dedications''. You must delete all sections
-entitled ``Endorsements.''
-
- at unnumberedsec COLLECTIONS OF DOCUMENTS
-
-You may make a collection consisting of the Document and other documents
-released under this License, and replace the individual copies of this
-License in the various documents with a single copy that is included in
-the collection, provided that you follow the rules of this License for
-verbatim copying of each of the documents in all other respects.
-
-You may extract a single document from such a collection, and distribute
-it individually under this License, provided you insert a copy of this
-License into the extracted document, and follow this License in all
-other respects regarding verbatim copying of that document.
-
- at unnumberedsec AGGREGATION WITH INDEPENDENT WORKS
-
-A compilation of the Document or its derivatives with other separate
-and independent documents or works, in or on a volume of a storage or
-distribution medium, does not as a whole count as a Modified Version
-of the Document, provided no compilation copyright is claimed for the
-compilation. Such a compilation is called an ``aggregate'', and this
-License does not apply to the other self-contained works thus compiled
-with the Document, on account of their being thus compiled, if they
-are not themselves derivative works of the Document.
-
-If the Cover Text requirement of section 3 is applicable to these
-copies of the Document, then if the Document is less than one quarter
-of the entire aggregate, the Document's Cover Texts may be placed on
-covers that surround only the Document within the aggregate.
-Otherwise they must appear on covers around the whole aggregate.
-
- at unnumberedsec TRANSLATION
-
-Translation is considered a kind of modification, so you may
-distribute translations of the Document under the terms of section 4.
-Replacing Invariant Sections with translations requires special
-permission from their copyright holders, but you may include
-translations of some or all Invariant Sections in addition to the
-original versions of these Invariant Sections. You may include a
-translation of this License provided that you also include the
-original English version of this License. In case of a disagreement
-between the translation and the original English version of this
-License, the original English version will prevail.
-
- at unnumberedsec TERMINATION
-
-You may not copy, modify, sublicense, or distribute the Document except
-as expressly provided for under this License. Any other attempt to
-copy, modify, sublicense or distribute the Document is void, and will
-automatically terminate your rights under this License. However,
-parties who have received copies, or rights, from you under this
-License will not have their licenses terminated so long as such
-parties remain in full compliance.
-
- at unnumberedsec FUTURE REVISIONS OF THIS LICENSE
-
-The Free Software Foundation may publish new, revised versions
-of the GNU Free Documentation License from time to time. Such new
-versions will be similar in spirit to the present version, but may
-differ in detail to address new problems or concerns. See
-http://www.gnu.org/copyleft/.
-
-Each version of the License is given a distinguishing version number.
-If the Document specifies that a particular numbered version of this
-License ``or any later version'' applies to it, you have the option of
-following the terms and conditions either of that specified version or
-of any later version that has been published (not as a draft) by the
-Free Software Foundation. If the Document does not specify a version
-number of this License, you may choose any version ever published (not
-as a draft) by the Free Software Foundation.
-
-
-
- at unnumberedsec ADDENDUM: How to use this License for your documents
-
-To use this License in a document you have written, include a copy of
-the License in the document and put the following copyright and
-license notices just after the title page:
-
- at display
-Copyright (c) YEAR YOUR NAME.
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1
-or any later version published by the Free Software Foundation;
-with the Invariant Sections being LIST THEIR TITLES, with the
-Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
-A copy of the license is included in the section entitled "GNU
-Free Documentation License".
- at end display
-
-If you have no Invariant Sections, write ``with no Invariant Sections''
-instead of saying which ones are invariant. If you have no
-Front-Cover Texts, write ``no Front-Cover Texts'' instead of
-``Front-Cover Texts being LIST''; likewise for Back-Cover Texts.
-
-If your document contains nontrivial examples of program code, we
-recommend releasing these examples in parallel under your choice of
-free software license, such as the GNU General Public License,
-to permit their use in free software.
-
- at c @bye
Copied: gnucash/trunk/src/doc/design/function-index.texi (from rev 23343, gnucash/trunk/src/doc/design/function-index.texinfo)
===================================================================
--- gnucash/trunk/src/doc/design/function-index.texi (rev 0)
+++ gnucash/trunk/src/doc/design/function-index.texi 2013-10-28 01:02:53 UTC (rev 23344)
@@ -0,0 +1,4 @@
+ at node Function Index, Data Type Index, User Preferences, Top
+ at unnumbered Function Index
+
+ at printindex fn
Deleted: gnucash/trunk/src/doc/design/function-index.texinfo
===================================================================
--- gnucash/trunk/src/doc/design/function-index.texinfo 2013-10-27 21:57:42 UTC (rev 23343)
+++ gnucash/trunk/src/doc/design/function-index.texinfo 2013-10-28 01:02:53 UTC (rev 23344)
@@ -1,4 +0,0 @@
- at node Function Index, Data Type Index, User Preferences, Top
- at unnumbered Function Index
-
- at printindex fn
Copied: gnucash/trunk/src/doc/design/gnucash-design.texi (from rev 23343, gnucash/trunk/src/doc/design/gnucash-design.texinfo)
===================================================================
--- gnucash/trunk/src/doc/design/gnucash-design.texi (rev 0)
+++ gnucash/trunk/src/doc/design/gnucash-design.texi 2013-10-28 01:02:53 UTC (rev 23344)
@@ -0,0 +1,239 @@
+\input texinfo @c -*-texinfo-*-
+ at c %**start of header
+ at setfilename gnucash-design.info
+ at settitle GnuCash Design Document
+ at c %**end of header
+
+ at comment 'version.texi' is a magic filename that, when included,
+ at comment will be auto-generated courtesy of automake.
+ at include version.texi
+
+ at ifinfo
+ at format
+
+ at dircategory Programming
+
+ at direntry
+* gnucash: (gnucash-design). Design of the GnuCash program
+ at end direntry
+
+ at end format
+ at end ifinfo
+
+ at ifinfo
+This file documents the design of the GnuCash program.
+
+Copyright 2000 Gnumatic Incorporated
+
+This is Edition @value{EDITION}, last updated @value{UPDATED},
+of the @cite{GnuCash Design Document}, version @value{VERSION}.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1
+or any later version published by the Free Software Foundation;
+with the Invariant Sections being LIST THEIR TITLES, with the
+Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+A copy of the license is included in the section entitled "GNU
+Free Documentation License".
+
+ at ignore
+Permission is granted to process this file through TeX
+and print the results, provided the printed document
+carries a copying permission notice identical to this
+one except for the removal of this paragraph (this
+paragraph not being relevant to the printed manual).
+ at end ignore
+
+ at end ifinfo
+
+ at titlepage
+ at title GnuCash Design Document
+ at subtitle Edition @value{EDITION} for Version @value{VERSION}
+ at author Rob Browning
+ at author Bill Gribble
+ at author Robert Merkel
+ at author Dave Peticolas
+ at author Linas Vepstas
+ at page
+ at vskip 0pt plus 1filll
+ at copyright{} 2000 Gnumatic Incorporated
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1
+or any later version published by the Free Software Foundation;
+with the Invariant Sections being LIST THEIR TITLES, with the
+Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+A copy of the license is included in the section entitled "GNU
+Free Documentation License".
+ at end titlepage
+
+ at ifnottex
+ at node Top, GNU Free Documentation License, (dir), (dir)
+ at top GnuCash Design Document
+This is Edition @value{EDITION}, last updated @value{UPDATED},
+of the @cite{GnuCash Design Document}, version @value{VERSION}.
+ at end ifnottex
+
+ at menu
+* GNU Free Documentation License::
+* Introduction::
+* Top Level::
+* Engine::
+* Component Manager::
+* Register::
+* Reports::
+* User Preferences::
+* Function Index::
+* Data Type Index::
+* Concept Index::
+
+
+ at detailmenu
+ --- The Detailed Node Listing ---
+
+Engine
+
+* Engine Introduction::
+* Using and Extending the Engine API::
+* Globally Unique Identifiers::
+* Numeric Library::
+* Key-Value Pair Frames::
+* Events::
+* Commodities::
+* Commodity Tables::
+* Prices::
+* Price Databases::
+* Splits::
+* Transactions::
+* Accounts::
+* Account Groups::
+* GNCBooks::
+* Scrub::
+
+Globally Unique Identifiers
+
+* When to use GUIDs::
+* GUID Types::
+* How to use GUIDs::
+* GUIDs and GnuCash Entities::
+* The GUID Generator::
+
+Numeric Library
+
+* Standard Numeric Arguments::
+* Creating Numeric Objects::
+* Basic Arithmetic Operations::
+* Numeric Comparisons and Predicates::
+* Numeric Denominator Conversion::
+* Numeric Floating Point Conversion::
+* Numeric String Conversion::
+* Numeric Error Handling ::
+* Numeric Example::
+
+Key-Value Pair Frames
+
+* Key-Value Policy::
+* kvp_frame::
+* kvp_value::
+* kvp_list::
+
+Events
+
+* Event API::
+
+Commodities
+
+* General Commodity API::
+* Commodity Getters::
+* Commodity Setters::
+
+Commodity Tables
+
+* General Commodity Table API::
+* Commodity Table Access API::
+* Commodity Table Modification API::
+
+Prices
+
+* Price Implementation Details::
+* General Price API::
+* Price Getters::
+* Price Setters::
+
+Price Databases
+
+* Price Lists::
+* General Price Database API::
+
+Splits
+
+* General Split API::
+* Split Getters::
+* Split Setters::
+
+Transactions
+
+* General Transaction API::
+* Transaction Getters::
+* Transaction Setters::
+
+Accounts
+
+* Account Types::
+* General Account API::
+* Account Type API::
+* Account Getters::
+
+Account Groups
+
+* General Account Group API::
+* Account Group Account API::
+
+GNCBooks
+
+* GNCBook API::
+
+Component Manager
+
+* Component Manager Introduction::
+
+Register
+
+* Cells::
+* Cellblocks::
+* Table::
+* Split Register::
+
+Cells
+
+* BasicCell::
+
+Reports
+
+* Creating a Report::
+
+User Preferences
+
+* Option Databases::
+* Option Types::
+* Option Creation::
+* Option Values::
+
+ at end detailmenu
+ at end menu
+
+ at include fdl.texi
+ at include intro.texi
+ at include top-level.texi
+ at include engine.texi
+ at include component-manager.texi
+ at include register.texi
+ at include reports.texi
+ at include user-preferences.texi
+ at include function-index.texi
+ at include type-index.texi
+ at include concept-index.texi
+
+ at summarycontents
+ at contents
+
+ at bye
Deleted: gnucash/trunk/src/doc/design/gnucash-design.texinfo
===================================================================
--- gnucash/trunk/src/doc/design/gnucash-design.texinfo 2013-10-27 21:57:42 UTC (rev 23343)
+++ gnucash/trunk/src/doc/design/gnucash-design.texinfo 2013-10-28 01:02:53 UTC (rev 23344)
@@ -1,239 +0,0 @@
-\input texinfo @c -*-texinfo-*-
- at c %**start of header
- at setfilename gnucash-design.info
- at settitle GnuCash Design Document
- at c %**end of header
-
- at comment 'version.texi' is a magic filename that, when included,
- at comment will be auto-generated courtesy of automake.
- at include version.texi
-
- at ifinfo
- at format
-
- at dircategory Programming
-
- at direntry
-* gnucash: (gnucash-design). Design of the GnuCash program
- at end direntry
-
- at end format
- at end ifinfo
-
- at ifinfo
-This file documents the design of the GnuCash program.
-
-Copyright 2000 Gnumatic Incorporated
-
-This is Edition @value{EDITION}, last updated @value{UPDATED},
-of the @cite{GnuCash Design Document}, version @value{VERSION}.
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1
-or any later version published by the Free Software Foundation;
-with the Invariant Sections being LIST THEIR TITLES, with the
-Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
-A copy of the license is included in the section entitled "GNU
-Free Documentation License".
-
- at ignore
-Permission is granted to process this file through TeX
-and print the results, provided the printed document
-carries a copying permission notice identical to this
-one except for the removal of this paragraph (this
-paragraph not being relevant to the printed manual).
- at end ignore
-
- at end ifinfo
-
- at titlepage
- at title GnuCash Design Document
- at subtitle Edition @value{EDITION} for Version @value{VERSION}
- at author Rob Browning
- at author Bill Gribble
- at author Robert Merkel
- at author Dave Peticolas
- at author Linas Vepstas
- at page
- at vskip 0pt plus 1filll
- at copyright{} 2000 Gnumatic Incorporated
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1
-or any later version published by the Free Software Foundation;
-with the Invariant Sections being LIST THEIR TITLES, with the
-Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
-A copy of the license is included in the section entitled "GNU
-Free Documentation License".
- at end titlepage
-
- at ifnottex
- at node Top, GNU Free Documentation License, (dir), (dir)
- at top GnuCash Design Document
-This is Edition @value{EDITION}, last updated @value{UPDATED},
-of the @cite{GnuCash Design Document}, version @value{VERSION}.
- at end ifnottex
-
- at menu
-* GNU Free Documentation License::
-* Introduction::
-* Top Level::
-* Engine::
-* Component Manager::
-* Register::
-* Reports::
-* User Preferences::
-* Function Index::
-* Data Type Index::
-* Concept Index::
-
-
- at detailmenu
- --- The Detailed Node Listing ---
-
-Engine
-
-* Engine Introduction::
-* Using and Extending the Engine API::
-* Globally Unique Identifiers::
-* Numeric Library::
-* Key-Value Pair Frames::
-* Events::
-* Commodities::
-* Commodity Tables::
-* Prices::
-* Price Databases::
-* Splits::
-* Transactions::
-* Accounts::
-* Account Groups::
-* GNCBooks::
-* Scrub::
-
-Globally Unique Identifiers
-
-* When to use GUIDs::
-* GUID Types::
-* How to use GUIDs::
-* GUIDs and GnuCash Entities::
-* The GUID Generator::
-
-Numeric Library
-
-* Standard Numeric Arguments::
-* Creating Numeric Objects::
-* Basic Arithmetic Operations::
-* Numeric Comparisons and Predicates::
-* Numeric Denominator Conversion::
-* Numeric Floating Point Conversion::
-* Numeric String Conversion::
-* Numeric Error Handling ::
-* Numeric Example::
-
-Key-Value Pair Frames
-
-* Key-Value Policy::
-* kvp_frame::
-* kvp_value::
-* kvp_list::
-
-Events
-
-* Event API::
-
-Commodities
-
-* General Commodity API::
-* Commodity Getters::
-* Commodity Setters::
-
-Commodity Tables
-
-* General Commodity Table API::
-* Commodity Table Access API::
-* Commodity Table Modification API::
-
-Prices
-
-* Price Implementation Details::
-* General Price API::
-* Price Getters::
-* Price Setters::
-
-Price Databases
-
-* Price Lists::
-* General Price Database API::
-
-Splits
-
-* General Split API::
-* Split Getters::
-* Split Setters::
-
-Transactions
-
-* General Transaction API::
-* Transaction Getters::
-* Transaction Setters::
-
-Accounts
-
-* Account Types::
-* General Account API::
-* Account Type API::
-* Account Getters::
-
-Account Groups
-
-* General Account Group API::
-* Account Group Account API::
-
-GNCBooks
-
-* GNCBook API::
-
-Component Manager
-
-* Component Manager Introduction::
-
-Register
-
-* Cells::
-* Cellblocks::
-* Table::
-* Split Register::
-
-Cells
-
-* BasicCell::
-
-Reports
-
-* Creating a Report::
-
-User Preferences
-
-* Option Databases::
-* Option Types::
-* Option Creation::
-* Option Values::
-
- at end detailmenu
- at end menu
-
- at include fdl.texinfo
- at include intro.texinfo
- at include top-level.texinfo
- at include engine.texinfo
- at include component-manager.texinfo
- at include register.texinfo
- at include reports.texinfo
- at include user-preferences.texinfo
- at include function-index.texinfo
- at include type-index.texinfo
- at include concept-index.texinfo
-
- at summarycontents
- at contents
-
- at bye
Copied: gnucash/trunk/src/doc/design/intro.texi (from rev 23343, gnucash/trunk/src/doc/design/intro.texinfo)
===================================================================
--- gnucash/trunk/src/doc/design/intro.texi (rev 0)
+++ gnucash/trunk/src/doc/design/intro.texi 2013-10-28 01:02:53 UTC (rev 23344)
@@ -0,0 +1,49 @@
+ at node Introduction, Top Level, GNU Free Documentation License, Top
+ at unnumbered Introduction
+
+ at strong{This whole document is completely outdated. Don't read this. All
+function names and every described structure has changed
+completely. Only read this if you want to know how gnucash looked like
+in 1999. This is completely outdated!}
+
+This document defines the design and architecture of the GnuCash
+program, an application for tracking finances. GnuCash is composed
+of several subsystems or modules. This document describes each module,
+specifying its interface and, where appropriate, its implementation,
+as well as describing the interactions between each module.
+
+ at unnumberedsec Who Should Read This Document?
+
+Anyone who plans on making a significant change or addition to GnuCash's
+functionality should read this document. By adhering to the structure
+presented here, your contribution will be more likely to work correctly
+with existing and future features.
+
+ at unnumberedsec Goals
+
+GnuCash is intended to be a finance and accounting program for
+individuals and small businesses. As such, it should have the
+following primary features:
+
+ at itemize
+
+ at item
+A sound underlying model for financial entities such as currencies,
+transactions, and accounts.
+
+ at item
+A user interface which provides an efficient way to accomplish
+common tasks, such as transaction entry, account reconciliation,
+etc.
+
+ at item
+The ability to generate and print standard financial reports
+such as Income Statements, Balance Sheets, etc.
+
+ at item
+The ability to generate and print graphs of financial information.
+
+ at end itemize
+
+A more comprehensive list of current and planned features for GnuCash
+is located at @uref{http://cvs.gnucash.org/linux/gnucash/projects.html}.
Deleted: gnucash/trunk/src/doc/design/intro.texinfo
===================================================================
--- gnucash/trunk/src/doc/design/intro.texinfo 2013-10-27 21:57:42 UTC (rev 23343)
+++ gnucash/trunk/src/doc/design/intro.texinfo 2013-10-28 01:02:53 UTC (rev 23344)
@@ -1,49 +0,0 @@
- at node Introduction, Top Level, GNU Free Documentation License, Top
- at unnumbered Introduction
-
- at strong{This whole document is completely outdated. Don't read this. All
-function names and every described structure has changed
-completely. Only read this if you want to know how gnucash looked like
-in 1999. This is completely outdated!}
-
-This document defines the design and architecture of the GnuCash
-program, an application for tracking finances. GnuCash is composed
-of several subsystems or modules. This document describes each module,
-specifying its interface and, where appropriate, its implementation,
-as well as describing the interactions between each module.
-
- at unnumberedsec Who Should Read This Document?
-
-Anyone who plans on making a significant change or addition to GnuCash's
-functionality should read this document. By adhering to the structure
-presented here, your contribution will be more likely to work correctly
-with existing and future features.
-
- at unnumberedsec Goals
-
-GnuCash is intended to be a finance and accounting program for
-individuals and small businesses. As such, it should have the
-following primary features:
-
- at itemize
-
- at item
-A sound underlying model for financial entities such as currencies,
-transactions, and accounts.
-
- at item
-A user interface which provides an efficient way to accomplish
-common tasks, such as transaction entry, account reconciliation,
-etc.
-
- at item
-The ability to generate and print standard financial reports
-such as Income Statements, Balance Sheets, etc.
-
- at item
-The ability to generate and print graphs of financial information.
-
- at end itemize
-
-A more comprehensive list of current and planned features for GnuCash
-is located at @uref{http://cvs.gnucash.org/linux/gnucash/projects.html}.
Copied: gnucash/trunk/src/doc/design/register.texi (from rev 23343, gnucash/trunk/src/doc/design/register.texinfo)
===================================================================
--- gnucash/trunk/src/doc/design/register.texi (rev 0)
+++ gnucash/trunk/src/doc/design/register.texi 2013-10-28 01:02:53 UTC (rev 23344)
@@ -0,0 +1,162 @@
+ at node Register, Reports, Component Manager, Top
+ at chapter Register
+ at cindex Register
+
+ at strong{This whole document is completely outdated. Don't read this. All
+function names and every described structure has changed
+completely. Only read this if you want to know how gnucash looked like
+in 1999. This is completely outdated!}
+
+The register is an infrastructure for building a modular matrix of cells
+in which each cell may be specialized to perform a particular function,
+e.g., to read dates, numerical amounts, or text. The register has been
+designed to be easy to extend, modular, easy to maintain, and memory
+efficient. It is intended to be used for building financial apps and
+spread-sheets.
+
+The register object should not have any 'knowledge' of the accounting
+model of GnuCash or of the workings of the main application. The
+register should not be specific to a particular GUI (such as Gnome/GTK).
+It should be possible to use the register in a stand-alone fashion.
+
+The register is built from several types of components: Cells,
+Cellblocks, Cursors, the Table, and the Split Register.
+
+ at menu
+* Cells::
+* Cellblocks::
+* Table::
+* Split Register::
+ at end menu
+
+
+ at node Cells, Cellblocks, Register, Register
+ at section Cells
+
+A @dfn{Cell} is an active object which is designed to read a specific
+kind of user input. A Cell object has callbacks that are called when
+the user enters the cell (e.g. by mouse-clicking on a cell in a table,
+or tabbing into it), when the user attempts to modify text in the cell
+(e.g. by typing in it), and when the user leaves the cell (e.g. by
+mouse-clicking elsewhere, or tabbing away).
+
+Special-purpose cells can be created by "inheriting" from the basic cell
+object. Thus, there are special-purpose cells for handling dates,
+pull-down menus, text fields with auto-completion from a list of
+alternatives, monetary amounts, etc.
+
+Cells implementations may or may not contain GUI code. Cells which
+require only that text be displayed are completely "GUI-independent",
+that is, they depend on the underlying table to display the text. Cells
+which require additional GUI elements (such as pull-down menus) must
+implement the proper GUI handling on their own (using, e.g., GTK).
+
+ at menu
+* BasicCell::
+ at end menu
+
+
+ at node BasicCell, , Cells, Cells
+ at subsection BasicCell
+ at tindex BasicCell
+
+The @dfn{BasicCell} interface defines the core functionality that all
+cells must implement. A BasicCell contains the following data members.
+
+ at table @code
+
+ at item char *value
+The 'value' of the cell stored as a character string.
+
+ at item GdkWChar *w_value
+The 'value' of the cell stores as a wide character string.
+
+ at item gint value_len
+The length of w_value.
+
+ at item guint32 changed
+This member is set to have all 1-bits (2^32 - 1) to indicate the
+cell contents have been changed from the register value.
+
+ at item guint32 conditionally_changed
+This member is set to have all 1-bits (2^32 - 1) to indicate the
+cell contents have been changed from the register value, but that
+the register should not be considered to be changed unless other
+cells have been changed (not conditionally).
+
+ at item char * blank_help
+This member is a text string which may be used by a GUI implementation
+to display an informative help string when the value of a cell is empty
+(perhaps prompting the user to enter a particular kind of value).
+
+ at end table
+
+
+ at node Cellblocks, Table, Cells, Register
+ at section Cellblocks
+
+A @dfn{Cellblock} is an array of active cells. The cells are laid out in
+rows and columns. The cellblock serves as a convenient container for
+organizing active cells in an array. Through the mechanism of Cursors
+(defined below), it allows a group of cells to be treated as a single
+transactional entity. That is, the cursor/cellblock allows all edits to
+a groups of cells to be simultaneously committed or rejected by
+underlying engines. This makes it appropriate for use as a GUI for
+transaction-processing applications with two-phase commit requirements.
+
+
+ at node Table, Split Register, Cellblocks, Register
+ at section Table
+
+The @dfn{Table} is a displayed matrix. The table is a complex object;
+it is @emph{not} merely a cellblock. The table provides all of the GUI
+infrastructure for displaying a row-column matrix of strings.
+
+The table provides one very important function for minimizing memory
+usage for large matrixes -- the notion of a @dfn{Cursor}. The cursor is
+a cellblock (an array of active cells) that is moved to the location
+that the user is currently editing. The cursor "virtualizes" cell
+functions; that is, it makes it seem to the user as if all cells in the
+table are active, when in fact the only cell that actually needs to be
+active is the one that the user is currently editing.
+
+The table design allows multiple cursors to be defined. When a user
+enters a cell, the appropriate cursor is positioned within the table.
+Cursors cannot overlap: any given cell can be mapped to at most one
+cursor. Multiple-cursor support allows tables to be designed that have a
+non-uniform layout. For example, the multiple-cursor support can be used
+to define a tree structure of headings and sub-headings, where the
+layout/format of the heading is different from the sub-headings. A
+financial example is a table which lists splits underneath their parent
+transaction. This is very different from a checkbook register, where all
+entries are uniform, and can be handled with a single repeated cursor.
+
+Users of the table must provide a TableView object which provides an API
+the table uses to obtain information about the data it is displaying
+such as strings, colors, etc. Thus, the table represents the non-GUI
+portion of the View object in the Model-View-Controller paradigm.
+
+
+ at node Split Register, , Table, Register
+ at section Split Register
+
+The split register is a special-purpose object aimed at the display
+of financial transactions. It includes cells for the date, prices,
+balances, transfer accounts, etc. The register is where the cells,
+cursor and table get put together into a unified whole. The register
+defines specific, actual layouts and widths of the date, price, etc.
+cells in a table. It includes a table header, and defines more than
+ten specific layouts: bank, credit-card, stock, general ledger, etc.
+
+The split register implementation is divided into two components. The
+first component (src/register/splitreg.[ch]) defines the basic structure
+and implementation of a split register, but does not specifically use or
+depend on the other GnuCash modules, including the Engine. Of course,
+this implementation was created with the engine financial structures in
+mind.
+
+The second component (src/SplitLedger.[ch]) implements the full register
+behavior (the Controller in MVC) and makes full use of the Engine
+API. This component is responsible for loading transactions and splits
+into the register, modifying transactions and splits according to user
+input, and accomplishing tasks such as performing automatic completion.
Deleted: gnucash/trunk/src/doc/design/register.texinfo
===================================================================
--- gnucash/trunk/src/doc/design/register.texinfo 2013-10-27 21:57:42 UTC (rev 23343)
+++ gnucash/trunk/src/doc/design/register.texinfo 2013-10-28 01:02:53 UTC (rev 23344)
@@ -1,162 +0,0 @@
- at node Register, Reports, Component Manager, Top
- at chapter Register
- at cindex Register
-
- at strong{This whole document is completely outdated. Don't read this. All
-function names and every described structure has changed
-completely. Only read this if you want to know how gnucash looked like
-in 1999. This is completely outdated!}
-
-The register is an infrastructure for building a modular matrix of cells
-in which each cell may be specialized to perform a particular function,
-e.g., to read dates, numerical amounts, or text. The register has been
-designed to be easy to extend, modular, easy to maintain, and memory
-efficient. It is intended to be used for building financial apps and
-spread-sheets.
-
-The register object should not have any 'knowledge' of the accounting
-model of GnuCash or of the workings of the main application. The
-register should not be specific to a particular GUI (such as Gnome/GTK).
-It should be possible to use the register in a stand-alone fashion.
-
-The register is built from several types of components: Cells,
-Cellblocks, Cursors, the Table, and the Split Register.
-
- at menu
-* Cells::
-* Cellblocks::
-* Table::
-* Split Register::
- at end menu
-
-
- at node Cells, Cellblocks, Register, Register
- at section Cells
-
-A @dfn{Cell} is an active object which is designed to read a specific
-kind of user input. A Cell object has callbacks that are called when
-the user enters the cell (e.g. by mouse-clicking on a cell in a table,
-or tabbing into it), when the user attempts to modify text in the cell
-(e.g. by typing in it), and when the user leaves the cell (e.g. by
-mouse-clicking elsewhere, or tabbing away).
-
-Special-purpose cells can be created by "inheriting" from the basic cell
-object. Thus, there are special-purpose cells for handling dates,
-pull-down menus, text fields with auto-completion from a list of
-alternatives, monetary amounts, etc.
-
-Cells implementations may or may not contain GUI code. Cells which
-require only that text be displayed are completely "GUI-independent",
-that is, they depend on the underlying table to display the text. Cells
-which require additional GUI elements (such as pull-down menus) must
-implement the proper GUI handling on their own (using, e.g., GTK).
-
- at menu
-* BasicCell::
- at end menu
-
-
- at node BasicCell, , Cells, Cells
- at subsection BasicCell
- at tindex BasicCell
-
-The @dfn{BasicCell} interface defines the core functionality that all
-cells must implement. A BasicCell contains the following data members.
-
- at table @code
-
- at item char *value
-The 'value' of the cell stored as a character string.
-
- at item GdkWChar *w_value
-The 'value' of the cell stores as a wide character string.
-
- at item gint value_len
-The length of w_value.
-
- at item guint32 changed
-This member is set to have all 1-bits (2^32 - 1) to indicate the
-cell contents have been changed from the register value.
-
- at item guint32 conditionally_changed
-This member is set to have all 1-bits (2^32 - 1) to indicate the
-cell contents have been changed from the register value, but that
-the register should not be considered to be changed unless other
-cells have been changed (not conditionally).
-
- at item char * blank_help
-This member is a text string which may be used by a GUI implementation
-to display an informative help string when the value of a cell is empty
-(perhaps prompting the user to enter a particular kind of value).
-
- at end table
-
-
- at node Cellblocks, Table, Cells, Register
- at section Cellblocks
-
-A @dfn{Cellblock} is an array of active cells. The cells are laid out in
-rows and columns. The cellblock serves as a convenient container for
-organizing active cells in an array. Through the mechanism of Cursors
-(defined below), it allows a group of cells to be treated as a single
-transactional entity. That is, the cursor/cellblock allows all edits to
-a groups of cells to be simultaneously committed or rejected by
-underlying engines. This makes it appropriate for use as a GUI for
-transaction-processing applications with two-phase commit requirements.
-
-
- at node Table, Split Register, Cellblocks, Register
- at section Table
-
-The @dfn{Table} is a displayed matrix. The table is a complex object;
-it is @emph{not} merely a cellblock. The table provides all of the GUI
-infrastructure for displaying a row-column matrix of strings.
-
-The table provides one very important function for minimizing memory
-usage for large matrixes -- the notion of a @dfn{Cursor}. The cursor is
-a cellblock (an array of active cells) that is moved to the location
-that the user is currently editing. The cursor "virtualizes" cell
-functions; that is, it makes it seem to the user as if all cells in the
-table are active, when in fact the only cell that actually needs to be
-active is the one that the user is currently editing.
-
-The table design allows multiple cursors to be defined. When a user
-enters a cell, the appropriate cursor is positioned within the table.
-Cursors cannot overlap: any given cell can be mapped to at most one
-cursor. Multiple-cursor support allows tables to be designed that have a
-non-uniform layout. For example, the multiple-cursor support can be used
-to define a tree structure of headings and sub-headings, where the
-layout/format of the heading is different from the sub-headings. A
-financial example is a table which lists splits underneath their parent
-transaction. This is very different from a checkbook register, where all
-entries are uniform, and can be handled with a single repeated cursor.
-
-Users of the table must provide a TableView object which provides an API
-the table uses to obtain information about the data it is displaying
-such as strings, colors, etc. Thus, the table represents the non-GUI
-portion of the View object in the Model-View-Controller paradigm.
-
-
- at node Split Register, , Table, Register
- at section Split Register
-
-The split register is a special-purpose object aimed at the display
-of financial transactions. It includes cells for the date, prices,
-balances, transfer accounts, etc. The register is where the cells,
-cursor and table get put together into a unified whole. The register
-defines specific, actual layouts and widths of the date, price, etc.
-cells in a table. It includes a table header, and defines more than
-ten specific layouts: bank, credit-card, stock, general ledger, etc.
-
-The split register implementation is divided into two components. The
-first component (src/register/splitreg.[ch]) defines the basic structure
-and implementation of a split register, but does not specifically use or
-depend on the other GnuCash modules, including the Engine. Of course,
-this implementation was created with the engine financial structures in
-mind.
-
-The second component (src/SplitLedger.[ch]) implements the full register
-behavior (the Controller in MVC) and makes full use of the Engine
-API. This component is responsible for loading transactions and splits
-into the register, modifying transactions and splits according to user
-input, and accomplishing tasks such as performing automatic completion.
Copied: gnucash/trunk/src/doc/design/reports.texi (from rev 23343, gnucash/trunk/src/doc/design/reports.texinfo)
===================================================================
--- gnucash/trunk/src/doc/design/reports.texi (rev 0)
+++ gnucash/trunk/src/doc/design/reports.texi 2013-10-28 01:02:53 UTC (rev 23344)
@@ -0,0 +1,95 @@
+ at node Reports, User Preferences, Register, Top
+ at chapter Reports
+ at cindex Reports
+
+ at strong{This whole document is completely outdated. Don't read this. All
+function names and every described structure has changed
+completely. Only read this if you want to know how gnucash looked like
+in 1999. This is completely outdated!}
+
+The reporting infrastructure is designed facilitate the creation
+of sophisticated reports including tables, graphs, and hyperlinks.
+The infrastructure includes functionality to support the following:
+
+ at itemize
+
+ at item
+Creation of tables, with headings, subheadings, totals, and subtotals.
+
+ at item
+Formatting of dates & numbers.
+
+ at item
+Currency conversions.
+
+ at item
+Creation of graphs such as pie and bar charts.
+
+ at item
+Creation of hyperlinks to other reports and to other GnuCash
+objects such as registers.
+
+ at end itemize
+
+ at menu
+* Creating a Report::
+ at end menu
+
+
+ at node Creating a Report, , Reports, Reports
+ at section Creating a Report
+
+To define a report, your report must have
+
+ at code{(gnc:support <your_report_name>)}
+
+and should have
+
+ at code{(gnc:depend "report-utilities.scm")}
+
+as well as
+
+ at code{(gnc:depend "report-html.scm")}
+
+if you wish to use the html generation facilities. You should
+avoid creating HTML directly wherever possible.
+
+To autoload your report, you should add the line @code{(gnc:depend
+<your_report_name>)} to the file @file{src/scm/report/report-list.scm}.
+
+ at code{(gnc:depend "date-utilities.scm")}
+
+has lots of date-manipulation functions you'll almost certainly need.
+
+To define a report, you call @code{(gnc:define-report)}. This function
+can accept a variable number of arguments, but at the moment four
+distinct arguments are recognised, as in the following from
+the transaction report:
+
+ at example
+ (gnc:define-report
+ 'version 1
+ 'name (N_ "Transaction Report")
+ 'options-generator trep-options-generator
+ 'renderer trep-renderer)
+ at end example
+
+ at table @code
+
+ at item version
+This is the version number of the report, which is currently ignored.
+
+ at item name
+This is the name of the report. It should be marked as translatable,
+but the name should be given in untranslated form, hence the use of
+ at code{(N_ )}.
+
+ at item options-generator
+This should be a function that takes no arguments and returns an options
+structure with the options for the report. The options interface is
+currently not fully documented, but should be.
+
+ at item renderer
+This is the function which renders the HTML.
+
+ at end table
Deleted: gnucash/trunk/src/doc/design/reports.texinfo
===================================================================
--- gnucash/trunk/src/doc/design/reports.texinfo 2013-10-27 21:57:42 UTC (rev 23343)
+++ gnucash/trunk/src/doc/design/reports.texinfo 2013-10-28 01:02:53 UTC (rev 23344)
@@ -1,95 +0,0 @@
- at node Reports, User Preferences, Register, Top
- at chapter Reports
- at cindex Reports
-
- at strong{This whole document is completely outdated. Don't read this. All
-function names and every described structure has changed
-completely. Only read this if you want to know how gnucash looked like
-in 1999. This is completely outdated!}
-
-The reporting infrastructure is designed facilitate the creation
-of sophisticated reports including tables, graphs, and hyperlinks.
-The infrastructure includes functionality to support the following:
-
- at itemize
-
- at item
-Creation of tables, with headings, subheadings, totals, and subtotals.
-
- at item
-Formatting of dates & numbers.
-
- at item
-Currency conversions.
-
- at item
-Creation of graphs such as pie and bar charts.
-
- at item
-Creation of hyperlinks to other reports and to other GnuCash
-objects such as registers.
-
- at end itemize
-
- at menu
-* Creating a Report::
- at end menu
-
-
- at node Creating a Report, , Reports, Reports
- at section Creating a Report
-
-To define a report, your report must have
-
- at code{(gnc:support <your_report_name>)}
-
-and should have
-
- at code{(gnc:depend "report-utilities.scm")}
-
-as well as
-
- at code{(gnc:depend "report-html.scm")}
-
-if you wish to use the html generation facilities. You should
-avoid creating HTML directly wherever possible.
-
-To autoload your report, you should add the line @code{(gnc:depend
-<your_report_name>)} to the file @file{src/scm/report/report-list.scm}.
-
- at code{(gnc:depend "date-utilities.scm")}
-
-has lots of date-manipulation functions you'll almost certainly need.
-
-To define a report, you call @code{(gnc:define-report)}. This function
-can accept a variable number of arguments, but at the moment four
-distinct arguments are recognised, as in the following from
-the transaction report:
-
- at example
- (gnc:define-report
- 'version 1
- 'name (N_ "Transaction Report")
- 'options-generator trep-options-generator
- 'renderer trep-renderer)
- at end example
-
- at table @code
-
- at item version
-This is the version number of the report, which is currently ignored.
-
- at item name
-This is the name of the report. It should be marked as translatable,
-but the name should be given in untranslated form, hence the use of
- at code{(N_ )}.
-
- at item options-generator
-This should be a function that takes no arguments and returns an options
-structure with the options for the report. The options interface is
-currently not fully documented, but should be.
-
- at item renderer
-This is the function which renders the HTML.
-
- at end table
Copied: gnucash/trunk/src/doc/design/top-level.texi (from rev 23343, gnucash/trunk/src/doc/design/top-level.texinfo)
===================================================================
--- gnucash/trunk/src/doc/design/top-level.texi (rev 0)
+++ gnucash/trunk/src/doc/design/top-level.texi 2013-10-28 01:02:53 UTC (rev 23344)
@@ -0,0 +1,168 @@
+ at node Top Level, Engine, Introduction, Top
+ at chapter Architectural Overview
+
+ at strong{This whole document is completely outdated. Don't read this. All
+function names and every described structure has changed
+completely. Only read this if you want to know how gnucash looked like
+in 1999. This is completely outdated!}
+
+GnuCash is written primarily in two languages: C and Scheme. The
+engine/server is written in C primarily for speed, portability,
+stability and historical purposes. Much of the day-to-day workhorse code
+is written in Scheme, primarily for its power, expressiveness and ease
+of development. The user interface is Gtk/Gnome, some of it written in
+C, some in scheme, and some with the GUI designer tool Glade
+ at uref{glade.pn.org}.
+
+GnuCash is modular, thereby allowing separate individuals
+to maintain, develop and enhance certain modules without
+disturbing the overall development. (Never mind that
+modules help avoid spaghetti code and nasty, ugly hacks).
+The interfaces between modules are documented, and, for the
+most part, stable and unchanging.
+
+GnuCash currently consists of the following modules:
+
+
+ at section The Engine
+
+The @dfn{Engine} (located under the @file{src/engine} directory in the
+GnuCash codebase) provides an interface for creating, manipulating, and
+destroying three basic financial entities: Accounts, Transactions (known
+as Journal Entries in accounting practice), and Splits (known as Ledger
+Entries). These three entities are the central data structures of the
+GnuCash financial data model.
+
+The Engine code contains no GUI code whatsoever.
+
+ at subsection Query
+
+The @dfn{Query} module (@file{src/engine/Query.*}) provides an interface
+into the engine for finding transactions based on a set of criteria,
+such as description, date posted, account membership, etc. Simple
+queries can be combined using standard boolean operators.
+
+ at subsection File I/O
+
+The @dfn{File I/O} module (@file{src/engine/FileIO.*}) provides an
+interface for reading and writing a set of Accounts, Transactions, and
+Splits to a binary file. This module is deprecated.
+
+ at subsection XML I/O
+
+The @dfn{XML I/O} module (@file{src/engine/*xml*.*} and
+ at file{src/engine/*sixtp*.*}) provides an interface for reading and
+writing the engine information to an XML format.
+
+ at subsection Backend
+
+The @dfn{Backend} module (@file{src/engine/Backend*.*}) provides
+hooks to allow different modules to be used for storing and retrieving
+Engine data. There are two backends currently under development, a
+Postgresql backend (@file{src/engine/sql/*}) and an RPC backend
+(@file{src/engine/rpc/*}).
+
+
+ at section The Register
+
+The @dfn{Register} (@file{src/register}) implements a ledger-like
+GUI that allows the user to dynamically enter dates, prices, memos
+descriptions, etc. in an intuitive fashion that should be obvious to
+anyone who's used a checkbook register. The code is highly configurable,
+allowing the ledger columns and rows to be laid out in any way, with no
+restrictions on the function, type, and number of columns/rows. For
+example, one can define a ledger with three date fields, one price
+field, and four memo fields in a straightforward fashion. Cell handling
+objects support and automatically validate date entry, memo entry
+(w/auto-completion), prices, combo-boxes (pull-down menus), and
+multi-state check-boxes. Cells can be marked read-write, or
+output-only. Cells can be assigned unique colors. The currently
+active ledger row-block can be highlighted with a unique color.
+
+The register code is completely independent of the engine code, knows
+nothing about accounting or any of the other GnuCash subsystems. It
+can be used in independent projects that have nothing to do with
+accounting.
+
+
+ at section Reports
+
+The @dfn{Reports} module (@file{src/scm/report.scm},
+ at file{src/scm/reports}) is a scheme (guile) based system to create
+balance sheets, profit & loss statements, etc. by using the engine
+API to fetch and display data formatted in HTML.
+
+For the most part, this module uses the Query API to fetch the engine
+information instead of using the raw engine interface. This design uses
+Queries to extract the data and assemble it into a view-independent
+format. This data is then be converted to HTML reports and/or graphs
+such as bar and pie charts.
+
+
+ at section Graphs
+
+The @dfn{Graphs} module implements GUI graphs such as bar and pie
+charts. These graphs can be interactive in that the user can, for
+example, move pie wedges, and 'live' in that the user can click on graph
+subsections to see a detail graph or report of that particular
+subsection.
+
+This module is implemented using the GUPPI library being developed by
+Jon Trowbridge (@url{http://www.gnome.org/guppi}).
+
+
+ at section Price Quotes
+
+The @dfn{Price Quotes} module (@file{src/quotes}) is a Perl system to
+fetch stock price data off the Internet and insert it into the GnuCash
+Engine. This module requires the functionality of the Finance::Quote
+module available at SourceForge. The Finance::Quote module can fetch
+price quotes from many different sources including Yahoo, Yahoo Europe,
+and some international exchanges.
+
+The Finance::Quote module also supports fetching currency exchange
+rates. GnuCash will be extended to allow the fetching and use of
+currency exchange rates.
+
+
+ at section User Preferences
+
+The @dfn{User Preferences} module (@file{src/scm/options.scm},
+ at file{src/scm/prefs.scm}) provides an infrastructure for defining both
+user-configurable and internal preferences. Preferences are defined in
+scheme using several predefined preference types such as boolean,
+string, date, etc. Preferences are 'implemented' by providing a GUI
+which allows the user to see and change preference values. An API
+is provided to query preference values and to register callbacks
+which will be invoked when preferences change.
+
+Preference values which are different from the default values
+are stored as scheme forms in a user-specific preferences file
+(@file{~/.gnucash/config.auto}). This file is automatically
+loaded upon startup.
+
+
+ at section QIF Import
+
+The @dfn{QIF Import} module (@file{src/scm/qif-import}) provides
+functionality for importing QIF (Quicken Interchange Format) data
+into GnuCash.
+
+
+ at section GnuCash
+
+The GnuCash module (@file{src/gnome}, @file{src/register/gnome} and
+ at file{src/*.[ch]}) is the main GUI application. It consists of a
+collection of miscellaneous GUI code to glue together all of the pieces
+above into a coherent, point-and-click whole. It is meant to be easy to
+use and intuitive to the novice user without sacrificing the power and
+flexibility that a professional might expect. When people say that
+GnuCash is trying to be a "Quicken or MS Money look/work/act-alike",
+this is the piece that they are referring to. It really is meant to
+be a personal-finance manager with enough power for the power user
+and the ease of use for the beginner.
+
+Currently, the Gnome interface is the only operational interface. There
+is an obsolete Motif interface which is not maintained and which is
+removed in current CVS. There is also old Qt code (removed in current
+CVS) which won't compile, and most/all functions are missing.
Deleted: gnucash/trunk/src/doc/design/top-level.texinfo
===================================================================
--- gnucash/trunk/src/doc/design/top-level.texinfo 2013-10-27 21:57:42 UTC (rev 23343)
+++ gnucash/trunk/src/doc/design/top-level.texinfo 2013-10-28 01:02:53 UTC (rev 23344)
@@ -1,168 +0,0 @@
- at node Top Level, Engine, Introduction, Top
- at chapter Architectural Overview
-
- at strong{This whole document is completely outdated. Don't read this. All
-function names and every described structure has changed
-completely. Only read this if you want to know how gnucash looked like
-in 1999. This is completely outdated!}
-
-GnuCash is written primarily in two languages: C and Scheme. The
-engine/server is written in C primarily for speed, portability,
-stability and historical purposes. Much of the day-to-day workhorse code
-is written in Scheme, primarily for its power, expressiveness and ease
-of development. The user interface is Gtk/Gnome, some of it written in
-C, some in scheme, and some with the GUI designer tool Glade
- at uref{glade.pn.org}.
-
-GnuCash is modular, thereby allowing separate individuals
-to maintain, develop and enhance certain modules without
-disturbing the overall development. (Never mind that
-modules help avoid spaghetti code and nasty, ugly hacks).
-The interfaces between modules are documented, and, for the
-most part, stable and unchanging.
-
-GnuCash currently consists of the following modules:
-
-
- at section The Engine
-
-The @dfn{Engine} (located under the @file{src/engine} directory in the
-GnuCash codebase) provides an interface for creating, manipulating, and
-destroying three basic financial entities: Accounts, Transactions (known
-as Journal Entries in accounting practice), and Splits (known as Ledger
-Entries). These three entities are the central data structures of the
-GnuCash financial data model.
-
-The Engine code contains no GUI code whatsoever.
-
- at subsection Query
-
-The @dfn{Query} module (@file{src/engine/Query.*}) provides an interface
-into the engine for finding transactions based on a set of criteria,
-such as description, date posted, account membership, etc. Simple
-queries can be combined using standard boolean operators.
-
- at subsection File I/O
-
-The @dfn{File I/O} module (@file{src/engine/FileIO.*}) provides an
-interface for reading and writing a set of Accounts, Transactions, and
-Splits to a binary file. This module is deprecated.
-
- at subsection XML I/O
-
-The @dfn{XML I/O} module (@file{src/engine/*xml*.*} and
- at file{src/engine/*sixtp*.*}) provides an interface for reading and
-writing the engine information to an XML format.
-
- at subsection Backend
-
-The @dfn{Backend} module (@file{src/engine/Backend*.*}) provides
-hooks to allow different modules to be used for storing and retrieving
-Engine data. There are two backends currently under development, a
-Postgresql backend (@file{src/engine/sql/*}) and an RPC backend
-(@file{src/engine/rpc/*}).
-
-
- at section The Register
-
-The @dfn{Register} (@file{src/register}) implements a ledger-like
-GUI that allows the user to dynamically enter dates, prices, memos
-descriptions, etc. in an intuitive fashion that should be obvious to
-anyone who's used a checkbook register. The code is highly configurable,
-allowing the ledger columns and rows to be laid out in any way, with no
-restrictions on the function, type, and number of columns/rows. For
-example, one can define a ledger with three date fields, one price
-field, and four memo fields in a straightforward fashion. Cell handling
-objects support and automatically validate date entry, memo entry
-(w/auto-completion), prices, combo-boxes (pull-down menus), and
-multi-state check-boxes. Cells can be marked read-write, or
-output-only. Cells can be assigned unique colors. The currently
-active ledger row-block can be highlighted with a unique color.
-
-The register code is completely independent of the engine code, knows
-nothing about accounting or any of the other GnuCash subsystems. It
-can be used in independent projects that have nothing to do with
-accounting.
-
-
- at section Reports
-
-The @dfn{Reports} module (@file{src/scm/report.scm},
- at file{src/scm/reports}) is a scheme (guile) based system to create
-balance sheets, profit & loss statements, etc. by using the engine
-API to fetch and display data formatted in HTML.
-
-For the most part, this module uses the Query API to fetch the engine
-information instead of using the raw engine interface. This design uses
-Queries to extract the data and assemble it into a view-independent
-format. This data is then be converted to HTML reports and/or graphs
-such as bar and pie charts.
-
-
- at section Graphs
-
-The @dfn{Graphs} module implements GUI graphs such as bar and pie
-charts. These graphs can be interactive in that the user can, for
-example, move pie wedges, and 'live' in that the user can click on graph
-subsections to see a detail graph or report of that particular
-subsection.
-
-This module is implemented using the GUPPI library being developed by
-Jon Trowbridge (@url{http://www.gnome.org/guppi}).
-
-
- at section Price Quotes
-
-The @dfn{Price Quotes} module (@file{src/quotes}) is a Perl system to
-fetch stock price data off the Internet and insert it into the GnuCash
-Engine. This module requires the functionality of the Finance::Quote
-module available at SourceForge. The Finance::Quote module can fetch
-price quotes from many different sources including Yahoo, Yahoo Europe,
-and some international exchanges.
-
-The Finance::Quote module also supports fetching currency exchange
-rates. GnuCash will be extended to allow the fetching and use of
-currency exchange rates.
-
-
- at section User Preferences
-
-The @dfn{User Preferences} module (@file{src/scm/options.scm},
- at file{src/scm/prefs.scm}) provides an infrastructure for defining both
-user-configurable and internal preferences. Preferences are defined in
-scheme using several predefined preference types such as boolean,
-string, date, etc. Preferences are 'implemented' by providing a GUI
-which allows the user to see and change preference values. An API
-is provided to query preference values and to register callbacks
-which will be invoked when preferences change.
-
-Preference values which are different from the default values
-are stored as scheme forms in a user-specific preferences file
-(@file{~/.gnucash/config.auto}). This file is automatically
-loaded upon startup.
-
-
- at section QIF Import
-
-The @dfn{QIF Import} module (@file{src/scm/qif-import}) provides
-functionality for importing QIF (Quicken Interchange Format) data
-into GnuCash.
-
-
- at section GnuCash
-
-The GnuCash module (@file{src/gnome}, @file{src/register/gnome} and
- at file{src/*.[ch]}) is the main GUI application. It consists of a
-collection of miscellaneous GUI code to glue together all of the pieces
-above into a coherent, point-and-click whole. It is meant to be easy to
-use and intuitive to the novice user without sacrificing the power and
-flexibility that a professional might expect. When people say that
-GnuCash is trying to be a "Quicken or MS Money look/work/act-alike",
-this is the piece that they are referring to. It really is meant to
-be a personal-finance manager with enough power for the power user
-and the ease of use for the beginner.
-
-Currently, the Gnome interface is the only operational interface. There
-is an obsolete Motif interface which is not maintained and which is
-removed in current CVS. There is also old Qt code (removed in current
-CVS) which won't compile, and most/all functions are missing.
Copied: gnucash/trunk/src/doc/design/type-index.texi (from rev 23343, gnucash/trunk/src/doc/design/type-index.texinfo)
===================================================================
--- gnucash/trunk/src/doc/design/type-index.texi (rev 0)
+++ gnucash/trunk/src/doc/design/type-index.texi 2013-10-28 01:02:53 UTC (rev 23344)
@@ -0,0 +1,4 @@
+ at node Data Type Index, Concept Index, Function Index, Top
+ at unnumbered Date Type Index
+
+ at printindex tp
Deleted: gnucash/trunk/src/doc/design/type-index.texinfo
===================================================================
--- gnucash/trunk/src/doc/design/type-index.texinfo 2013-10-27 21:57:42 UTC (rev 23343)
+++ gnucash/trunk/src/doc/design/type-index.texinfo 2013-10-28 01:02:53 UTC (rev 23344)
@@ -1,4 +0,0 @@
- at node Data Type Index, Concept Index, Function Index, Top
- at unnumbered Date Type Index
-
- at printindex tp
Copied: gnucash/trunk/src/doc/design/user-preferences.texi (from rev 23343, gnucash/trunk/src/doc/design/user-preferences.texinfo)
===================================================================
--- gnucash/trunk/src/doc/design/user-preferences.texi (rev 0)
+++ gnucash/trunk/src/doc/design/user-preferences.texi 2013-10-28 01:02:53 UTC (rev 23344)
@@ -0,0 +1,306 @@
+ at node User Preferences, Function Index, Reports, Top
+ at chapter User Preferences
+ at cindex User Preferences
+
+ at strong{This whole document is completely outdated. Don't read this. All
+function names and every described structure has changed
+completely. Only read this if you want to know how gnucash looked like
+in 1999. This is completely outdated!}
+
+The options system is used to obtain user preferences, both globally,
+and when displaying a report. A wide variety of option types are
+supported, so it should be possible to create an option for just about
+any property the user might wish to specify. New option types can be
+added if necessary, but as the process requires detailed knowledge of
+GnuCash internals and GTK+/GNOME, it is not documented here.
+
+At present, users are most likely to come across the options system when
+designing custom reports, and are consequently mostly going to use the
+Scheme interface. There is also a C interface to much of the options
+system which is used to access preferences for the UI, but it is not yet
+documented.
+
+ at menu
+* Option Databases::
+* Option Types::
+* Option Creation::
+* Option Values::
+ at end menu
+
+ at node Option Databases, Option Types, User Preferences, User Preferences
+ at section Option Databases
+ at cindex Option Databases
+
+The options for a particular report are placed in an @dfn{options
+database}. For doing a report, the option-generator function must
+return an options database. The function
+
+ at code{(gnc:new-option)}
+
+returns a new, empty options database that you can then add options to.
+
+Options are organised into sections, which are each given a title string
+such as "Register" or "International". The UI displays each section on
+a seperate page. Each section has a number of options. Each option has
+a name that uniquely identifies it in that section, and an alphabetic
+ at dfn{sort tag} that determines the relative ordering of the options for
+display.
+
+ at node Option Types, Option Creation, Option Databases, User Preferences
+ at section Option Types
+
+Sometimes, GnuCash requires the user to specify true/false properties.
+Others properties most easily specified by selections from a list,
+others from a number, others still by selecting dates, or one or more
+accounts in the account hierachy, or even colors. GnuCash supports all
+of these and more:
+
+ at table @code
+
+ at item boolean
+
+These are displayed as a checkbox by the UI. They are used to specify
+yes/no answers.
+
+ at item string
+
+The UI provides a text entry box where arbitrary text may be entered.
+
+ at item font
+
+This allows users to select fonts from those available on the system.
+
+ at item currency
+
+For specifying a currency such as "USD", "AUD", "UKP" etc.
+
+ at item date
+
+For specifying dates. Depending on exactly what is required, you can
+choose to let the user specify an @dfn{absolute} date, a @dfn{relative}
+date such as "one month ago", or "start of the current accounting
+period", or let the user choose how whether to specify the required date
+in relative or absolute terms.
+
+ at item account-list
+
+For selecting a particular account or accounts. The UI displays a tree
+of the account hierachy.
+
+ at item multichoice
+
+For selecting one of a group of choices.
+
+ at item list
+
+Similar to the multichoice option, but allows the selection of one
+or more items from the group.
+
+ at item number-range
+
+For specifying a numeric quantity. The programmer can bound the range
+and precision of the quantity.
+
+ at item pixmap
+
+For selecting a pixmap located on the filesystem.
+
+ at item color
+
+For selecting a color value.
+
+ at item internal
+
+An option that isn't specified through an options dialog box. For
+instance, this is used to store the window dimensions so that they are
+preserved along with other preferences.
+ at end table
+
+ at node Option Creation, Option Values, Option Types, User Preferences
+ at section Option Creation
+ at cindex Option Creation
+
+To add an option to an options database, you first create that option,
+then register it with the database. For example, to create a simple
+checkbox-style boolean option, you would use
+ at code{gnc:make-simple-boolean-option} to create the option. Once
+created, you can then register the option. With
+ at code{gnc:register-option}.
+
+ at deffn Function gnc:register-option database option
+Register @var{option} in options database @var{database}
+ at end deffn
+
+The example below shows how to create an options database, then register
+a boolean option with it:
+
+ at example
+(define gnc:*hello-world-options* (gnc:new-options))
+(gnc:register-option gnc:*hello-world-options*
+ (gnc:make-simple-boolean-option
+ "Hello, World!" "Boolean Option"
+ "a" "This is a boolean option." #t))
+ at end example
+
+ at subsection Option Creation Functions
+
+ at deffn Function gnc:make-simple-boolean-option section name sort-tag documentation-string default-value
+
+Creates a boolean option, with option section @var{section} and name
+ at var{name} specified as strings. Note that the section and name strings
+uniquely specify the option for the option database that they get
+registered to, and are used for looking up the option when the value is
+required. @var{sort-tag} is a string tag that specifies the relative
+order when displaying the options. Options are displayed top to bottom
+in case-sensitive alphabetical order. @var{documentation-string} is a
+string containing a short string describing the purpose of the option,
+which the UI displays as a tooltip. @var{default-value} should be a
+boolean value indicating the default value of this option.
+
+Note that @var{section}, @var{name}, @var{sort-tag}, and
+ at var{documentation-string} are common to all the following functions.
+ at end deffn
+
+ at deffn Function gnc:make-complex-boolean-option section name sort-tag documentation-string default-value setter-function-called-cb option-widget-changed-cb
+
+As above, but the function specified in @var{option-widget-changed-cb}
+is called when the GUI widget representing the option is changed (the
+user clicks on the toggle button), and @var{setter-function-called-cb}
+is called when the option's setter is called (when the user selects "OK"
+or "Apply").
+
+One use for having a non-false @var{option-widget-changed-cb} is to make
+another option mutable (in concert with @code{gnc:option-set-sensitive},
+discussed later).
+ at end deffn
+
+ at deffn Function gnc:make-string-option section name sort-tag documentation-string default-value
+
+Make an option where the user can specify a string.
+
+ at end deffn
+
+ at deffn Function gnc:make-date-option section name sort-tag documentation-string default-getter show-time subtype relative-date-list
+
+Create a date option. There are three different variations of date
+options, specified by the variable @var{subtype}, which should be one of
+ at code{'relative}, @code{'absolute}, or @code{both}. @code{absolute}
+date options allow the selection of a specific day/month/year
+combination. @code{relative} date options allow the selection from a
+list of different dates specified in relation to the current date, such
+as "today", "start of the current month", or "six months ago". Finally
+ at code{both} allows the user to choose either using absolute or relative
+date options.
+ at end deffn
+ at var{default-getter} should be a @dfn{thunk} (Scheme function taking
+no arguments) that returns a pair. The car of the pair should contain
+either @code{'relative} or @code{'absolute}, to indicate whether the
+default value is relative or absolute. If the car is @code{relative},
+then the cdr should be a one of the relative date symbols listed in
+ at var{relative-date-list}. If the car is @code{absolute}, it should be a
+timepair containing the default date/time.
+
+ at var{show-time} is a boolean that indicates whether when selecting an
+absolute date, the user can specify a time. It is ignored if the
+ at var{subtype} is @code{relative}.
+
+ at var{relative-date-list} is a list of symbols that indicate the relative
+dates permitted. The symbols used must have been previously defined as
+indicating a particular relative date. @var{gnc:relative-dates}
+contains a list of symbols that have already been set up for the most
+common relative dates. FIXME: document relative date system.
+
+ at deffn Function gnc:make-multichoice-option section name sort-tag documentation-string default-value value-list
+
+Create a multichoice option. @var{value-list} is a list of vectors of
+length 3, each representing a different choice. Each vector should
+contain - in the following order:
+ at itemize
+ at item
+A symbol identifying this choice.
+ at item
+A string naming this choice - this string will be the main one
+displayed.
+ at item
+A string describing this choice slightly more fully. This string will
+appear as a tooltip.
+ at end itemize
+
+ at end deffn
+
+ at deffn Function gnc:make-list-option section name sort-key documentation-string default-values value-list
+
+Like a multichoice option, but users can select one or more values from
+a list. @var{default-values} is a list of selected values instead of
+just one.
+
+ at end deffn
+
+ at deffn Function gnc:make-font-option section name sort-tag documentation-string default-value
+
+Allow the user to specify the font. Font options store font descriptions as strings,
+like the X Logical Font Description. You must provide a default value, as there is unfortunately
+no easy way for the GUI to pick a default value.
+
+ at end deffn
+
+ at deffn Function gnc:make-color-option section name sort-key documentation-string default-value
+scale use-alpha?
+
+Allow the user to select a color. The default value should be a list of
+length 4 containing the red, green, blue, and alpha channel values for
+the color. The scale is the maximum value for a channel, and the
+use-alpha? is a boolean that, if false, disregards the alpha channel
+(note: if you don't know what an alpha channel is, you don't need it).
+
+ at end deffn
+
+ at deffn Function gnc:make-currency-option section name sort-tag documentation-string default-value
+
+Let the user specify a currency using a currency code. The GUI provides a specialised widget
+for currency selection.
+
+ at end deffn
+
+ at deffn Function gnc:make-account-list-option section name sort-tag documentation-string default-getter value-validator multiple-selection
+ at end deffn
+
+ at deffn Function gnc:make-internal-option section name sort-key documentation-string default-value
+Create an option that isn't controlled through the options GUI. This is
+used mainly by the GUI to store state that should be preserved from
+session to session but isn't really configurable from a dialog box,
+such as the size of the GnuCash main window.
+ at end deffn
+
+ at deffn Function gnc:make-number-range-option section name sort-tag documentation-string default-value lower-bound upper-bound num-decimals step-size
+
+Create an option for selecting a numerical quantity. lower-bound and upper-bound specify the domain of acceptable figures, and num-decimals specifies the range
+to which the option will be displayed (FIXME:and rounded to?). Step-size specifies the step size for the UI's up/down buttons.
+
+ at end deffn
+
+ at node Option Values, , Option Creation, User Preferences
+ at section Option Values
+ at cindex Option Values
+
+To get the value of an option, you must first lookup the option in
+the options database.
+
+ at deffn Function gnc:lookup-option options section name
+
+Looks up the option in section @var{section} and name @var{name} in the
+options database @var{options}.
+
+ at end deffn
+
+
+Once you have looked up the option, you can get its value using
+the function @code{gnc:option-value}.
+
+ at deffn Function gnc:option-value option
+
+Get the value of an option. Option values returned are of the same
+type as how the default values are specified (except the date option
+which needs to be fixed).
+
+ at end deffn
Deleted: gnucash/trunk/src/doc/design/user-preferences.texinfo
===================================================================
--- gnucash/trunk/src/doc/design/user-preferences.texinfo 2013-10-27 21:57:42 UTC (rev 23343)
+++ gnucash/trunk/src/doc/design/user-preferences.texinfo 2013-10-28 01:02:53 UTC (rev 23344)
@@ -1,306 +0,0 @@
- at node User Preferences, Function Index, Reports, Top
- at chapter User Preferences
- at cindex User Preferences
-
- at strong{This whole document is completely outdated. Don't read this. All
-function names and every described structure has changed
-completely. Only read this if you want to know how gnucash looked like
-in 1999. This is completely outdated!}
-
-The options system is used to obtain user preferences, both globally,
-and when displaying a report. A wide variety of option types are
-supported, so it should be possible to create an option for just about
-any property the user might wish to specify. New option types can be
-added if necessary, but as the process requires detailed knowledge of
-GnuCash internals and GTK+/GNOME, it is not documented here.
-
-At present, users are most likely to come across the options system when
-designing custom reports, and are consequently mostly going to use the
-Scheme interface. There is also a C interface to much of the options
-system which is used to access preferences for the UI, but it is not yet
-documented.
-
- at menu
-* Option Databases::
-* Option Types::
-* Option Creation::
-* Option Values::
- at end menu
-
- at node Option Databases, Option Types, User Preferences, User Preferences
- at section Option Databases
- at cindex Option Databases
-
-The options for a particular report are placed in an @dfn{options
-database}. For doing a report, the option-generator function must
-return an options database. The function
-
- at code{(gnc:new-option)}
-
-returns a new, empty options database that you can then add options to.
-
-Options are organised into sections, which are each given a title string
-such as "Register" or "International". The UI displays each section on
-a seperate page. Each section has a number of options. Each option has
-a name that uniquely identifies it in that section, and an alphabetic
- at dfn{sort tag} that determines the relative ordering of the options for
-display.
-
- at node Option Types, Option Creation, Option Databases, User Preferences
- at section Option Types
-
-Sometimes, GnuCash requires the user to specify true/false properties.
-Others properties most easily specified by selections from a list,
-others from a number, others still by selecting dates, or one or more
-accounts in the account hierachy, or even colors. GnuCash supports all
-of these and more:
-
- at table @code
-
- at item boolean
-
-These are displayed as a checkbox by the UI. They are used to specify
-yes/no answers.
-
- at item string
-
-The UI provides a text entry box where arbitrary text may be entered.
-
- at item font
-
-This allows users to select fonts from those available on the system.
-
- at item currency
-
-For specifying a currency such as "USD", "AUD", "UKP" etc.
-
- at item date
-
-For specifying dates. Depending on exactly what is required, you can
-choose to let the user specify an @dfn{absolute} date, a @dfn{relative}
-date such as "one month ago", or "start of the current accounting
-period", or let the user choose how whether to specify the required date
-in relative or absolute terms.
-
- at item account-list
-
-For selecting a particular account or accounts. The UI displays a tree
-of the account hierachy.
-
- at item multichoice
-
-For selecting one of a group of choices.
-
- at item list
-
-Similar to the multichoice option, but allows the selection of one
-or more items from the group.
-
- at item number-range
-
-For specifying a numeric quantity. The programmer can bound the range
-and precision of the quantity.
-
- at item pixmap
-
-For selecting a pixmap located on the filesystem.
-
- at item color
-
-For selecting a color value.
-
- at item internal
-
-An option that isn't specified through an options dialog box. For
-instance, this is used to store the window dimensions so that they are
-preserved along with other preferences.
- at end table
-
- at node Option Creation, Option Values, Option Types, User Preferences
- at section Option Creation
- at cindex Option Creation
-
-To add an option to an options database, you first create that option,
-then register it with the database. For example, to create a simple
-checkbox-style boolean option, you would use
- at code{gnc:make-simple-boolean-option} to create the option. Once
-created, you can then register the option. With
- at code{gnc:register-option}.
-
- at deffn Function gnc:register-option database option
-Register @var{option} in options database @var{database}
- at end deffn
-
-The example below shows how to create an options database, then register
-a boolean option with it:
-
- at example
-(define gnc:*hello-world-options* (gnc:new-options))
-(gnc:register-option gnc:*hello-world-options*
- (gnc:make-simple-boolean-option
- "Hello, World!" "Boolean Option"
- "a" "This is a boolean option." #t))
- at end example
-
- at subsection Option Creation Functions
-
- at deffn Function gnc:make-simple-boolean-option section name sort-tag documentation-string default-value
-
-Creates a boolean option, with option section @var{section} and name
- at var{name} specified as strings. Note that the section and name strings
-uniquely specify the option for the option database that they get
-registered to, and are used for looking up the option when the value is
-required. @var{sort-tag} is a string tag that specifies the relative
-order when displaying the options. Options are displayed top to bottom
-in case-sensitive alphabetical order. @var{documentation-string} is a
-string containing a short string describing the purpose of the option,
-which the UI displays as a tooltip. @var{default-value} should be a
-boolean value indicating the default value of this option.
-
-Note that @var{section}, @var{name}, @var{sort-tag}, and
- at var{documentation-string} are common to all the following functions.
- at end deffn
-
- at deffn Function gnc:make-complex-boolean-option section name sort-tag documentation-string default-value setter-function-called-cb option-widget-changed-cb
-
-As above, but the function specified in @var{option-widget-changed-cb}
-is called when the GUI widget representing the option is changed (the
-user clicks on the toggle button), and @var{setter-function-called-cb}
-is called when the option's setter is called (when the user selects "OK"
-or "Apply").
-
-One use for having a non-false @var{option-widget-changed-cb} is to make
-another option mutable (in concert with @code{gnc:option-set-sensitive},
-discussed later).
- at end deffn
-
- at deffn Function gnc:make-string-option section name sort-tag documentation-string default-value
-
-Make an option where the user can specify a string.
-
- at end deffn
-
- at deffn Function gnc:make-date-option section name sort-tag documentation-string default-getter show-time subtype relative-date-list
-
-Create a date option. There are three different variations of date
-options, specified by the variable @var{subtype}, which should be one of
- at code{'relative}, @code{'absolute}, or @code{both}. @code{absolute}
-date options allow the selection of a specific day/month/year
-combination. @code{relative} date options allow the selection from a
-list of different dates specified in relation to the current date, such
-as "today", "start of the current month", or "six months ago". Finally
- at code{both} allows the user to choose either using absolute or relative
-date options.
- at end deffn
- at var{default-getter} should be a @dfn{thunk} (Scheme function taking
-no arguments) that returns a pair. The car of the pair should contain
-either @code{'relative} or @code{'absolute}, to indicate whether the
-default value is relative or absolute. If the car is @code{relative},
-then the cdr should be a one of the relative date symbols listed in
- at var{relative-date-list}. If the car is @code{absolute}, it should be a
-timepair containing the default date/time.
-
- at var{show-time} is a boolean that indicates whether when selecting an
-absolute date, the user can specify a time. It is ignored if the
- at var{subtype} is @code{relative}.
-
- at var{relative-date-list} is a list of symbols that indicate the relative
-dates permitted. The symbols used must have been previously defined as
-indicating a particular relative date. @var{gnc:relative-dates}
-contains a list of symbols that have already been set up for the most
-common relative dates. FIXME: document relative date system.
-
- at deffn Function gnc:make-multichoice-option section name sort-tag documentation-string default-value value-list
-
-Create a multichoice option. @var{value-list} is a list of vectors of
-length 3, each representing a different choice. Each vector should
-contain - in the following order:
- at itemize
- at item
-A symbol identifying this choice.
- at item
-A string naming this choice - this string will be the main one
-displayed.
- at item
-A string describing this choice slightly more fully. This string will
-appear as a tooltip.
- at end itemize
-
- at end deffn
-
- at deffn Function gnc:make-list-option section name sort-key documentation-string default-values value-list
-
-Like a multichoice option, but users can select one or more values from
-a list. @var{default-values} is a list of selected values instead of
-just one.
-
- at end deffn
-
- at deffn Function gnc:make-font-option section name sort-tag documentation-string default-value
-
-Allow the user to specify the font. Font options store font descriptions as strings,
-like the X Logical Font Description. You must provide a default value, as there is unfortunately
-no easy way for the GUI to pick a default value.
-
- at end deffn
-
- at deffn Function gnc:make-color-option section name sort-key documentation-string default-value
-scale use-alpha?
-
-Allow the user to select a color. The default value should be a list of
-length 4 containing the red, green, blue, and alpha channel values for
-the color. The scale is the maximum value for a channel, and the
-use-alpha? is a boolean that, if false, disregards the alpha channel
-(note: if you don't know what an alpha channel is, you don't need it).
-
- at end deffn
-
- at deffn Function gnc:make-currency-option section name sort-tag documentation-string default-value
-
-Let the user specify a currency using a currency code. The GUI provides a specialised widget
-for currency selection.
-
- at end deffn
-
- at deffn Function gnc:make-account-list-option section name sort-tag documentation-string default-getter value-validator multiple-selection
- at end deffn
-
- at deffn Function gnc:make-internal-option section name sort-key documentation-string default-value
-Create an option that isn't controlled through the options GUI. This is
-used mainly by the GUI to store state that should be preserved from
-session to session but isn't really configurable from a dialog box,
-such as the size of the GnuCash main window.
- at end deffn
-
- at deffn Function gnc:make-number-range-option section name sort-tag documentation-string default-value lower-bound upper-bound num-decimals step-size
-
-Create an option for selecting a numerical quantity. lower-bound and upper-bound specify the domain of acceptable figures, and num-decimals specifies the range
-to which the option will be displayed (FIXME:and rounded to?). Step-size specifies the step size for the UI's up/down buttons.
-
- at end deffn
-
- at node Option Values, , Option Creation, User Preferences
- at section Option Values
- at cindex Option Values
-
-To get the value of an option, you must first lookup the option in
-the options database.
-
- at deffn Function gnc:lookup-option options section name
-
-Looks up the option in section @var{section} and name @var{name} in the
-options database @var{options}.
-
- at end deffn
-
-
-Once you have looked up the option, you can get its value using
-the function @code{gnc:option-value}.
-
- at deffn Function gnc:option-value option
-
-Get the value of an option. Option values returned are of the same
-type as how the default values are specified (except the date option
-which needs to be fixed).
-
- at end deffn
More information about the gnucash-changes
mailing list