mirror of
https://github.com/Gnucash/gnucash.git
synced 2025-02-25 18:55:30 -06:00
Remove texi design document in engine
It's extremely out of date and we no longer use it to keep track of our design decisions and suggestions. Only a section on KVP policy has been move into kvp_doc.txt as it may make sense there.
This commit is contained in:
Geert Janssens
parent
48b9fa80ce
commit
39aa5f9c09
5
.gitignore
vendored
5
.gitignore
vendored
@ -96,11 +96,6 @@ libgnucash/core-utils/test/test-gnc-uri-utils
|
||||
libgnucash/core-utils/test/test-resolve-file-path
|
||||
libgnucash/doc/doxygen.cfg
|
||||
libgnucash/doc/doxygen.log
|
||||
libgnucash/doc/design/gnucash-design.info
|
||||
libgnucash/doc/design/mdate-sh
|
||||
libgnucash/doc/design/stamp-vti
|
||||
libgnucash/doc/design/texinfo.tex
|
||||
libgnucash/doc/design/version.texi
|
||||
libgnucash/doc/html/
|
||||
libgnucash/engine/gncla-dir.h
|
||||
libgnucash/engine/gnucash
|
||||
|
||||
5
HACKING
5
HACKING
@ -10,11 +10,6 @@ In addition to this file, you should read the README file, which
|
||||
explains the details of getting the git source, building GnuCash,
|
||||
and creating patches for submission.
|
||||
|
||||
The src/doc/design directory contains a preliminary design document
|
||||
which you should read as well. You should also feel free to hack on
|
||||
the design document.
|
||||
|
||||
|
||||
Coding Style Conventions
|
||||
------------------------
|
||||
Please refer to https://wiki.gnucash.org/wiki/CodingStandard.
|
||||
|
||||
@ -105,13 +105,6 @@ Libraries/Deps
|
||||
to the main menu bar instead
|
||||
of one on the window.
|
||||
|
||||
makeinfo Not really needed, it
|
||||
just builds the
|
||||
mostly obsolete
|
||||
design documentation
|
||||
(superceded for the
|
||||
most part in Doxygen
|
||||
docs).
|
||||
doxygen For building the Doxygen API
|
||||
documentation.
|
||||
|
||||
|
||||
@ -690,9 +690,7 @@ Defaulting to today."))
|
||||
(current-time))
|
||||
|
||||
|
||||
;; There is no GNC:RELATIVE-DATES list like the one mentioned in
|
||||
;; gnucash-design.info, is there? Here are the currently defined
|
||||
;; items, loosely grouped.
|
||||
;; Here are the currently defined items, loosely grouped.
|
||||
;;today
|
||||
;;start-cal-year end-cal-year start-prev-year end-prev-year
|
||||
;;start-this-month end-this-month start-prev-month end-prev-month
|
||||
|
||||
@ -1,6 +1,3 @@
|
||||
if (NOT WIN32)
|
||||
add_subdirectory(design)
|
||||
endif()
|
||||
add_subdirectory(xml)
|
||||
|
||||
set(doc_FILES
|
||||
|
||||
@ -1,44 +0,0 @@
|
||||
|
||||
set(gnucash_design_TEXINFOS
|
||||
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
|
||||
)
|
||||
|
||||
execute_process(COMMAND date +%e OUTPUT_VARIABLE CURRENT_DATE OUTPUT_STRIP_TRAILING_WHITESPACE)
|
||||
execute_process(COMMAND date +%B OUTPUT_VARIABLE CURRENT_MONTH OUTPUT_STRIP_TRAILING_WHITESPACE)
|
||||
execute_process(COMMAND date +%Y OUTPUT_VARIABLE CURRENT_YEAR OUTPUT_STRIP_TRAILING_WHITESPACE)
|
||||
set(UPDATED "${CURRENT_DATE} ${CURRENT_MONTH} ${CURRENT_YEAR}")
|
||||
set(UPDATED_MONTH "${CURRENT_MONTH} ${CURRENT_YEAR}")
|
||||
|
||||
set(VERSION_TEXI_IN
|
||||
"@set UPDATED ${UPDATED}
|
||||
@set UPDATED-MONTH ${UPDATED_MONTH}
|
||||
@set EDITION ${PROJECT_VERSION}
|
||||
@set VERSION ${PROJECT_VERSION}
|
||||
")
|
||||
|
||||
file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/version.texi ${VERSION_TEXI_IN})
|
||||
file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/stamp-vti ${VERSION_TEXI_IN})
|
||||
|
||||
file(TO_NATIVE_PATH "${CMAKE_CURRENT_BINARY_DIR}" TEXI_BINARY_DIR)
|
||||
file(TO_NATIVE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/gnucash-design.texi" TEXI_SOURCE_FILE)
|
||||
find_program(MAKEINFO makeinfo)
|
||||
if (NOT ${MAKEINFO} STREQUAL "MAKEINFO-NOTFOUND")
|
||||
add_custom_command(
|
||||
OUTPUT gnucash-design.info
|
||||
COMMAND ${MAKEINFO} -I ${TEXI_BINARY_DIR} ${TEXI_SOURCE_FILE}
|
||||
DEPENDS ${gnucash_design_TEXINFOS}
|
||||
)
|
||||
endif()
|
||||
dist_add_generated (${BUILDING_FROM_VCS} gnucash-design.info)
|
||||
|
||||
set_dist_list(doc_design_DIST CMakeLists.txt gnucash-design.texi ${gnucash_design_TEXINFOS})
|
||||
@ -1,396 +0,0 @@
|
||||
@node Component Manager
|
||||
@chapter Component Manager
|
||||
@cindex Component Manager
|
||||
|
||||
@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.
|
||||
|
||||
|
||||
@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::
|
||||
@end menu
|
||||
|
||||
|
||||
@node Component Manager Introduction, Refresh Mechanism, Component Manager, Component Manager
|
||||
@section Introduction
|
||||
|
||||
The GnuCash GUI must manage many different components (registers,
|
||||
reconcile windows, reports, graphs, main window, etc.). Functions which
|
||||
need to be performed on or with GUI components include:
|
||||
|
||||
|
||||
@itemize
|
||||
|
||||
@item Refreshing components. When Engine objects (Accounts,
|
||||
Transactions, Splits, etc.) are created, modified, or destroyed,
|
||||
the GUI components which reference those objects must be refreshed.
|
||||
|
||||
@item Searching for existing components. For example, when the
|
||||
user chooses to 'Reconcile' an account with an existing reconcile
|
||||
dialog, that dialog should be raised to the top in lieu of creating
|
||||
a new reconcile dialog.
|
||||
|
||||
@item Closing components.
|
||||
|
||||
@end itemize
|
||||
|
||||
|
||||
In particular, keeping components updated in the face of changes in the
|
||||
Engine is a difficult problem. Requirements for handling refreshes
|
||||
include:
|
||||
|
||||
@itemize
|
||||
|
||||
@item The Engine should be able to inform user code when any account
|
||||
or transaction is changed (including changing their respective splits).
|
||||
This requirement is satisfied by the Engine Events.
|
||||
|
||||
@item The refresh mechanism should not have specific knowledge of
|
||||
individual windows and other GUI elements. It should be easy to
|
||||
add new refreshable elements to the mechanism.
|
||||
|
||||
@item Changes should be batchable with respect to refreshes, so that
|
||||
a sequence of changes only cause a refresh after the last change
|
||||
in a batch. Batching should be nestable, for coding simplicity.
|
||||
|
||||
@item For very large batches of changes (loading files) we need to be
|
||||
able to turn off the mechanism entirely, perform the changes, and then
|
||||
perform a global, forced refresh. This should also be nestable.
|
||||
|
||||
@item The Engine should not be managing GUI components.
|
||||
|
||||
@item The refresh mechanism should be extendable to a multi-user
|
||||
situation in which changes can come from external components.
|
||||
|
||||
@item Components should be able to specify which Engine entities
|
||||
can cause refreshes. This requirement allows the implementation
|
||||
to avoid unnecessary refreshing.
|
||||
|
||||
@end itemize
|
||||
|
||||
|
||||
@node Refresh Mechanism, CM Initialization and Shutdown, Component Manager Introduction, Component Manager
|
||||
@section Refresh Mechanism
|
||||
@cindex Refresh Mechanism
|
||||
|
||||
The major design decisions of the CM relate to the refresh
|
||||
mechanism. The refresh mechanism consists of two parts, the Engine
|
||||
component and the GUI component. The Engine component is the
|
||||
Event mechanism (@pxref{Events}), while the GUI component is the
|
||||
Component Manager, which provide refresh functionality as well
|
||||
as other services.
|
||||
|
||||
The diagram below illustrated the design of the GnuCash refresh
|
||||
mechanism.
|
||||
|
||||
@example
|
||||
----------
|
||||
| |
|
||||
| Engine |
|
||||
| |
|
||||
----------
|
||||
/|\
|
||||
|
|
||||
|--- Events (from Engine)
|
||||
|
|
||||
\|/
|
||||
-------------------------
|
||||
| |
|
||||
| Component Manager |
|
||||
| |
|
||||
-------------------------
|
||||
/ /|\ \ GUI Commands
|
||||
/ | \--- including refresh
|
||||
/ \|/ \ invocations (from CM)
|
||||
----------------- -----------------
|
||||
| | | |
|
||||
| GUI Component | | GUI Component | ...
|
||||
| | | |
|
||||
----------------- -----------------
|
||||
@end example
|
||||
|
||||
The top-level component is the Engine, which emits Events to the
|
||||
Component Manager. In fact, the Engine will send events to any
|
||||
registered handler, but in GnuCash, only the CM registers with
|
||||
the engine. All other GUI components register with the CM.
|
||||
|
||||
The CM invokes the refresh handlers of GUI components based on the
|
||||
Engine events received the CM has received as well as information
|
||||
provided by the GUI components (such as which specific Engine
|
||||
entities the components are 'watching').
|
||||
|
||||
|
||||
@node CM Initialization and Shutdown, Refresh Handlers, Refresh Mechanism, Component Manager
|
||||
@section Initialization and Shutdown
|
||||
|
||||
@deftypefun void gnc_component_manager_init (void)
|
||||
Initialize the Component Manager. This should be called
|
||||
before using an other CM functions.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun void gnc_component_manager_shutdown (void)
|
||||
Shutdown the Component Manager. This should be called
|
||||
to release Component Manager resources.
|
||||
@end deftypefun
|
||||
|
||||
|
||||
@node Refresh Handlers, Close Handlers, CM Initialization and Shutdown, Component Manager
|
||||
@section Refresh Handlers
|
||||
@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:
|
||||
|
||||
@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.
|
||||
@end deftp
|
||||
|
||||
When a refresh handler is invoked, it should perform the following actions:
|
||||
|
||||
@enumerate
|
||||
|
||||
@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.
|
||||
|
||||
@enumerate
|
||||
|
||||
@item Use the @code{GUID} lookup functions (such as
|
||||
@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.
|
||||
|
||||
@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 occurred for the Engine
|
||||
object in question. The @var{changes} hash is a mapping from
|
||||
@code{GUID}s to @code{EventInfo} structures. An @code{EventInfo}
|
||||
structure has a single member, @code{event_mask}, of type
|
||||
@code{GNCEngineEventType}. The @code{event_mask} is a logical or of the
|
||||
@code{GNC_EVENT_CREATE}, @code{GNC_EVENT_MODIFY}, and
|
||||
@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:
|
||||
|
||||
@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.
|
||||
@end deftypefun
|
||||
|
||||
@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.
|
||||
|
||||
@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.
|
||||
|
||||
@item Refresh the component if necessary. This includes updating the
|
||||
GUI as well as internal structures to reflect the new state of Engine
|
||||
objects.
|
||||
|
||||
@end enumerate
|
||||
|
||||
|
||||
@node Close Handlers, Registering and Unregistering Components, Refresh Handlers, Component Manager
|
||||
@section Close Handlers
|
||||
|
||||
A close handler is a function with the following type signature:
|
||||
|
||||
@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.
|
||||
@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.
|
||||
|
||||
|
||||
@node Registering and Unregistering Components, Watching Engine Objects, Close Handlers, Component Manager
|
||||
@section Registering and Unregistering Components
|
||||
|
||||
@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}.
|
||||
|
||||
@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
|
||||
@code{NO_COMPONENT} if there was an error.
|
||||
@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.
|
||||
|
||||
@deftypefun void gnc_unregister_gui_component (gint @var{component_id})
|
||||
Unregister the component with id @var{component} from the CM.
|
||||
@end deftypefun
|
||||
|
||||
@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
|
||||
@var{user_data} as a user data pointer.
|
||||
@end deftypefun
|
||||
|
||||
|
||||
@node Watching Engine Objects, Controlling Refreshes, Registering and Unregistering Components, Component Manager
|
||||
@section Watching Engine Objects
|
||||
|
||||
@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
|
||||
@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.
|
||||
@end deftypefun
|
||||
|
||||
@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.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun void gnc_gui_component_clear_watches (gint @var{component_id})
|
||||
Clear all watches for the component with id @var{component_id}.
|
||||
@end deftypefun
|
||||
|
||||
|
||||
@node Controlling Refreshes, Finding Components, Watching Engine Objects, Component Manager
|
||||
@section Controlling Refreshes
|
||||
|
||||
@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.
|
||||
@end deftypefun
|
||||
|
||||
@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 occurred 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.
|
||||
@end deftypefun
|
||||
|
||||
@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.
|
||||
@end deftypefun
|
||||
|
||||
@deftypefun gboolean gnc_gui_refresh_suspended (void)
|
||||
Returns TRUE if GUI refreshing is currently suspended.
|
||||
@end deftypefun
|
||||
|
||||
|
||||
@node Finding Components, Iterating over Components, Controlling Refreshes, Component Manager
|
||||
@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:
|
||||
|
||||
@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.
|
||||
@end deftp
|
||||
|
||||
@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.
|
||||
@end deftypefun
|
||||
|
||||
@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.
|
||||
@end deftypefun
|
||||
|
||||
|
||||
@node Iterating over Components, , Finding Components, Component Manager
|
||||
@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:
|
||||
|
||||
@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},
|
||||
@var{component_id} of a particular component, as well as the
|
||||
@var{iter_data} supplied in the iteration API call.
|
||||
@end deftp
|
||||
|
||||
@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
|
||||
@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.
|
||||
@end deftypefun
|
||||
@ -1,4 +0,0 @@
|
||||
@node Concept Index, , Data Type Index, Top
|
||||
@unnumbered Concept Index
|
||||
|
||||
@printindex cp
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,384 +0,0 @@
|
||||
@node GNU Free Documentation License, Introduction, Top, Top
|
||||
@unnumbered GNU Free Documentation License
|
||||
|
||||
@c This file is intended to be included in another file.
|
||||
|
||||
@center Version 1.1, March 2000
|
||||
|
||||
@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.
|
||||
@end display
|
||||
|
||||
@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.
|
||||
|
||||
@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.
|
||||
|
||||
@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.
|
||||
|
||||
@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.
|
||||
|
||||
@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:
|
||||
|
||||
@enumerate A
|
||||
@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.
|
||||
|
||||
@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).
|
||||
|
||||
@item
|
||||
State on the Title page the name of the publisher of the
|
||||
Modified Version, as the publisher.
|
||||
|
||||
@item
|
||||
Preserve all the copyright notices of the Document.
|
||||
|
||||
@item
|
||||
Add an appropriate copyright notice for your modifications
|
||||
adjacent to the other copyright notices.
|
||||
|
||||
@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.
|
||||
|
||||
@item
|
||||
Preserve in that license notice the full lists of Invariant Sections
|
||||
and required Cover Texts given in the Document's license notice.
|
||||
|
||||
@item
|
||||
Include an unaltered copy of this License.
|
||||
|
||||
@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.
|
||||
|
||||
@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.
|
||||
|
||||
@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.
|
||||
|
||||
@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.
|
||||
|
||||
@item
|
||||
Delete any section entitled ``Endorsements''. Such a section
|
||||
may not be included in the Modified Version.
|
||||
|
||||
@item
|
||||
Do not retitle any existing section as ``Endorsements''
|
||||
or to conflict in title with any Invariant Section.
|
||||
@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.
|
||||
|
||||
@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.''
|
||||
|
||||
@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.
|
||||
|
||||
@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.
|
||||
|
||||
@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.
|
||||
|
||||
@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.
|
||||
|
||||
@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
|
||||
https://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.
|
||||
|
||||
|
||||
|
||||
@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:
|
||||
|
||||
@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".
|
||||
@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.
|
||||
|
||||
@c @bye
|
||||
@ -1,4 +0,0 @@
|
||||
@node Function Index, Data Type Index, User Preferences, Top
|
||||
@unnumbered Function Index
|
||||
|
||||
@printindex fn
|
||||
@ -1,239 +0,0 @@
|
||||
\input texinfo @c -*-texinfo-*-
|
||||
@c %**start of header
|
||||
@setfilename gnucash-design.info
|
||||
@settitle GnuCash Design Document
|
||||
@c %**end of header
|
||||
|
||||
@comment 'version.texi' is a magic filename that, when included,
|
||||
@comment will be auto-generated courtesy of automake.
|
||||
@include version.texi
|
||||
|
||||
@ifinfo
|
||||
@format
|
||||
|
||||
@dircategory Programming
|
||||
|
||||
@direntry
|
||||
* gnucash: (gnucash-design). Design of the GnuCash program
|
||||
@end direntry
|
||||
|
||||
@end format
|
||||
@end ifinfo
|
||||
|
||||
@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".
|
||||
|
||||
@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).
|
||||
@end ignore
|
||||
|
||||
@end ifinfo
|
||||
|
||||
@titlepage
|
||||
@title GnuCash Design Document
|
||||
@subtitle Edition @value{EDITION} for Version @value{VERSION}
|
||||
@author Rob Browning
|
||||
@author Bill Gribble
|
||||
@author Robert Merkel
|
||||
@author Dave Peticolas
|
||||
@author Linas Vepstas
|
||||
@page
|
||||
@vskip 0pt plus 1filll
|
||||
@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".
|
||||
@end titlepage
|
||||
|
||||
@ifnottex
|
||||
@node Top, GNU Free Documentation License, (dir), (dir)
|
||||
@top GnuCash Design Document
|
||||
This is Edition @value{EDITION}, last updated @value{UPDATED},
|
||||
of the @cite{GnuCash Design Document}, version @value{VERSION}.
|
||||
@end ifnottex
|
||||
|
||||
@menu
|
||||
* GNU Free Documentation License::
|
||||
* Introduction::
|
||||
* Top Level::
|
||||
* Engine::
|
||||
* Component Manager::
|
||||
* Register::
|
||||
* Reports::
|
||||
* User Preferences::
|
||||
* Function Index::
|
||||
* Data Type Index::
|
||||
* Concept Index::
|
||||
|
||||
|
||||
@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::
|
||||
* KvpValue::
|
||||
* 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::
|
||||
|
||||
@end detailmenu
|
||||
@end menu
|
||||
|
||||
@include fdl.texi
|
||||
@include intro.texi
|
||||
@include top-level.texi
|
||||
@include engine.texi
|
||||
@include component-manager.texi
|
||||
@include register.texi
|
||||
@include reports.texi
|
||||
@include user-preferences.texi
|
||||
@include function-index.texi
|
||||
@include type-index.texi
|
||||
@include concept-index.texi
|
||||
|
||||
@summarycontents
|
||||
@contents
|
||||
|
||||
@bye
|
||||
@ -1,49 +0,0 @@
|
||||
@node Introduction, Top Level, GNU Free Documentation License, Top
|
||||
@unnumbered Introduction
|
||||
|
||||
@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.
|
||||
|
||||
@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.
|
||||
|
||||
@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:
|
||||
|
||||
@itemize
|
||||
|
||||
@item
|
||||
A sound underlying model for financial entities such as currencies,
|
||||
transactions, and accounts.
|
||||
|
||||
@item
|
||||
A user interface which provides an efficient way to accomplish
|
||||
common tasks, such as transaction entry, account reconciliation,
|
||||
etc.
|
||||
|
||||
@item
|
||||
The ability to generate and print standard financial reports
|
||||
such as Income Statements, Balance Sheets, etc.
|
||||
|
||||
@item
|
||||
The ability to generate and print graphs of financial information.
|
||||
|
||||
@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}.
|
||||
@ -1,162 +0,0 @@
|
||||
@node Register, Reports, Component Manager, Top
|
||||
@chapter Register
|
||||
@cindex Register
|
||||
|
||||
@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.
|
||||
|
||||
@menu
|
||||
* Cells::
|
||||
* Cellblocks::
|
||||
* Table::
|
||||
* Split Register::
|
||||
@end menu
|
||||
|
||||
|
||||
@node Cells, Cellblocks, Register, Register
|
||||
@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).
|
||||
|
||||
@menu
|
||||
* BasicCell::
|
||||
@end menu
|
||||
|
||||
|
||||
@node BasicCell, , Cells, Cells
|
||||
@subsection BasicCell
|
||||
@tindex BasicCell
|
||||
|
||||
The @dfn{BasicCell} interface defines the core functionality that all
|
||||
cells must implement. A BasicCell contains the following data members.
|
||||
|
||||
@table @code
|
||||
|
||||
@item char *value
|
||||
The 'value' of the cell stored as a character string.
|
||||
|
||||
@item GdkWChar *w_value
|
||||
The 'value' of the cell stores as a wide character string.
|
||||
|
||||
@item gint value_len
|
||||
The length of w_value.
|
||||
|
||||
@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.
|
||||
|
||||
@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).
|
||||
|
||||
@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).
|
||||
|
||||
@end table
|
||||
|
||||
|
||||
@node Cellblocks, Table, Cells, Register
|
||||
@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.
|
||||
|
||||
|
||||
@node Table, Split Register, Cellblocks, Register
|
||||
@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.
|
||||
|
||||
|
||||
@node Split Register, , Table, Register
|
||||
@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 journal, 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.
|
||||
@ -1,95 +0,0 @@
|
||||
@node Reports, User Preferences, Register, Top
|
||||
@chapter Reports
|
||||
@cindex Reports
|
||||
|
||||
@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:
|
||||
|
||||
@itemize
|
||||
|
||||
@item
|
||||
Creation of tables, with headings, subheadings, totals, and subtotals.
|
||||
|
||||
@item
|
||||
Formatting of dates & numbers.
|
||||
|
||||
@item
|
||||
Currency conversions.
|
||||
|
||||
@item
|
||||
Creation of graphs such as pie and bar charts.
|
||||
|
||||
@item
|
||||
Creation of hyperlinks to other reports and to other GnuCash
|
||||
objects such as registers.
|
||||
|
||||
@end itemize
|
||||
|
||||
@menu
|
||||
* Creating a Report::
|
||||
@end menu
|
||||
|
||||
|
||||
@node Creating a Report, , Reports, Reports
|
||||
@section Creating a Report
|
||||
|
||||
To define a report, your report must have
|
||||
|
||||
@code{(gnc:support <your_report_name>)}
|
||||
|
||||
and should have
|
||||
|
||||
@code{(gnc:depend "report-utilities.scm")}
|
||||
|
||||
as well as
|
||||
|
||||
@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}.
|
||||
|
||||
@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:
|
||||
|
||||
@example
|
||||
(gnc:define-report
|
||||
'version 1
|
||||
'name (N_ "Transaction Report")
|
||||
'options-generator trep-options-generator
|
||||
'renderer trep-renderer)
|
||||
@end example
|
||||
|
||||
@table @code
|
||||
|
||||
@item version
|
||||
This is the version number of the report, which is currently ignored.
|
||||
|
||||
@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
|
||||
@code{(N_ )}.
|
||||
|
||||
@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.
|
||||
|
||||
@item renderer
|
||||
This is the function which renders the HTML.
|
||||
|
||||
@end table
|
||||
@ -1,168 +0,0 @@
|
||||
@node Top Level, Engine, Introduction, Top
|
||||
@chapter Architectural Overview
|
||||
|
||||
@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
|
||||
@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:
|
||||
|
||||
|
||||
@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.
|
||||
|
||||
@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.
|
||||
|
||||
@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.
|
||||
|
||||
@subsection XML I/O
|
||||
|
||||
The @dfn{XML I/O} module (@file{src/engine/*xml*.*} and
|
||||
@file{src/engine/*sixtp*.*}) provides an interface for reading and
|
||||
writing the engine information to an XML format.
|
||||
|
||||
@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/*}).
|
||||
|
||||
|
||||
@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.
|
||||
|
||||
|
||||
@section Reports
|
||||
|
||||
The @dfn{Reports} module (@file{src/scm/report.scm},
|
||||
@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.
|
||||
|
||||
|
||||
@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{https://www.gnome.org/guppi}).
|
||||
|
||||
|
||||
@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 from CPAN. The Finance::Quote module can fetch
|
||||
price quotes from many different sources including Alphavantage
|
||||
and several international exchanges and fund companies.
|
||||
|
||||
The Finance::Quote module also supports fetching currency exchange
|
||||
rates. GnuCash will be extended to allow the fetching and use of
|
||||
currency exchange rates.
|
||||
|
||||
|
||||
@section User Preferences
|
||||
|
||||
The @dfn{User Preferences} module (@file{src/scm/options.scm},
|
||||
@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.
|
||||
|
||||
|
||||
@section QIF Import
|
||||
|
||||
The @dfn{QIF Import} module (@file{src/scm/qif-import}) provides
|
||||
functionality for importing QIF (Quicken Interchange Format) data
|
||||
into GnuCash.
|
||||
|
||||
|
||||
@section GnuCash
|
||||
|
||||
The GnuCash module (@file{src/gnome}, @file{src/register/gnome} and
|
||||
@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.
|
||||
@ -1,4 +0,0 @@
|
||||
@node Data Type Index, Concept Index, Function Index, Top
|
||||
@unnumbered Date Type Index
|
||||
|
||||
@printindex tp
|
||||
@ -1,306 +0,0 @@
|
||||
@node User Preferences, Function Index, Reports, Top
|
||||
@chapter User Preferences
|
||||
@cindex User Preferences
|
||||
|
||||
@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.
|
||||
|
||||
@menu
|
||||
* Option Databases::
|
||||
* Option Types::
|
||||
* Option Creation::
|
||||
* Option Values::
|
||||
@end menu
|
||||
|
||||
@node Option Databases, Option Types, User Preferences, User Preferences
|
||||
@section Option Databases
|
||||
@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
|
||||
|
||||
@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 separate page. Each section has a number of options. Each option has
|
||||
a name that uniquely identifies it in that section, and an alphabetic
|
||||
@dfn{sort tag} that determines the relative ordering of the options for
|
||||
display.
|
||||
|
||||
@node Option Types, Option Creation, Option Databases, User Preferences
|
||||
@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 hierarchy, or even colors. GnuCash supports all
|
||||
of these and more:
|
||||
|
||||
@table @code
|
||||
|
||||
@item boolean
|
||||
|
||||
These are displayed as a checkbox by the UI. They are used to specify
|
||||
yes/no answers.
|
||||
|
||||
@item string
|
||||
|
||||
The UI provides a text entry box where arbitrary text may be entered.
|
||||
|
||||
@item font
|
||||
|
||||
This allows users to select fonts from those available on the system.
|
||||
|
||||
@item currency
|
||||
|
||||
For specifying a currency such as "USD", "AUD", "UKP" etc.
|
||||
|
||||
@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.
|
||||
|
||||
@item account-list
|
||||
|
||||
For selecting a particular account or accounts. The UI displays a tree
|
||||
of the account hierarchy.
|
||||
|
||||
@item multichoice
|
||||
|
||||
For selecting one of a group of choices.
|
||||
|
||||
@item list
|
||||
|
||||
Similar to the multichoice option, but allows the selection of one
|
||||
or more items from the group.
|
||||
|
||||
@item number-range
|
||||
|
||||
For specifying a numeric quantity. The programmer can bound the range
|
||||
and precision of the quantity.
|
||||
|
||||
@item pixmap
|
||||
|
||||
For selecting a pixmap located on the filesystem.
|
||||
|
||||
@item color
|
||||
|
||||
For selecting a color value.
|
||||
|
||||
@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.
|
||||
@end table
|
||||
|
||||
@node Option Creation, Option Values, Option Types, User Preferences
|
||||
@section Option Creation
|
||||
@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
|
||||
@code{gnc:make-simple-boolean-option} to create the option. Once
|
||||
created, you can then register the option. With
|
||||
@code{gnc:register-option}.
|
||||
|
||||
@deffn Function gnc:register-option database option
|
||||
Register @var{option} in options database @var{database}
|
||||
@end deffn
|
||||
|
||||
The example below shows how to create an options database, then register
|
||||
a boolean option with it:
|
||||
|
||||
@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))
|
||||
@end example
|
||||
|
||||
@subsection Option Creation Functions
|
||||
|
||||
@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
|
||||
@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
|
||||
@var{documentation-string} are common to all the following functions.
|
||||
@end deffn
|
||||
|
||||
@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).
|
||||
@end deffn
|
||||
|
||||
@deffn Function gnc:make-string-option section name sort-tag documentation-string default-value
|
||||
|
||||
Make an option where the user can specify a string.
|
||||
|
||||
@end deffn
|
||||
|
||||
@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
|
||||
@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
|
||||
@code{both} allows the user to choose either using absolute or relative
|
||||
date options.
|
||||
@end deffn
|
||||
@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
|
||||
@var{relative-date-list}. If the car is @code{absolute}, it should be a
|
||||
timepair containing the default date/time.
|
||||
|
||||
@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
|
||||
@var{subtype} is @code{relative}.
|
||||
|
||||
@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.
|
||||
|
||||
@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:
|
||||
@itemize
|
||||
@item
|
||||
A symbol identifying this choice.
|
||||
@item
|
||||
A string naming this choice - this string will be the main one
|
||||
displayed.
|
||||
@item
|
||||
A string describing this choice slightly more fully. This string will
|
||||
appear as a tooltip.
|
||||
@end itemize
|
||||
|
||||
@end deffn
|
||||
|
||||
@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.
|
||||
|
||||
@end deffn
|
||||
|
||||
@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.
|
||||
|
||||
@end deffn
|
||||
|
||||
@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).
|
||||
|
||||
@end deffn
|
||||
|
||||
@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.
|
||||
|
||||
@end deffn
|
||||
|
||||
@deffn Function gnc:make-account-list-option section name sort-tag documentation-string default-getter value-validator multiple-selection
|
||||
@end deffn
|
||||
|
||||
@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.
|
||||
@end deffn
|
||||
|
||||
@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.
|
||||
|
||||
@end deffn
|
||||
|
||||
@node Option Values, , Option Creation, User Preferences
|
||||
@section Option Values
|
||||
@cindex Option Values
|
||||
|
||||
To get the value of an option, you must first lookup the option in
|
||||
the options database.
|
||||
|
||||
@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}.
|
||||
|
||||
@end deffn
|
||||
|
||||
|
||||
Once you have looked up the option, you can get its value using
|
||||
the function @code{gnc:option-value}.
|
||||
|
||||
@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).
|
||||
|
||||
@end deffn
|
||||
@ -7,7 +7,6 @@ This is the new developer and design manual for GnuCash.
|
||||
The documentation is organised in a rough sequence:
|
||||
|
||||
-# \ref manualguide Start with the main GnuCash manual.
|
||||
-# \ref texihtml Design overview.
|
||||
-# \ref doxylist Individual topic overviews, linked into the
|
||||
full API reference for each topic, generated from source code.
|
||||
-# \ref maingeneral How to work with Doxygen in your own code.
|
||||
@ -19,12 +18,6 @@ Please refer to the main
|
||||
page</a> on the gnucash website which includes links to the
|
||||
GnuCash Manual and the Concepts Guide in various formats.
|
||||
|
||||
\subsection texihtml Documentation elsewhere in the source tree.
|
||||
|
||||
There is also the "GnuCash Design Overview" which can be generated
|
||||
from the source using texi2html from the texinfo files in
|
||||
src/doc/design, but this is even more outdated.
|
||||
|
||||
\section doxylist Doxygen overviews.
|
||||
|
||||
Where possible, each overview is dated - take care to review older texts
|
||||
|
||||
@ -7,8 +7,12 @@ There should be no GUI code in this subdirectory, and,
|
||||
ideally, it should build cleanly and independently of
|
||||
any GUI elements or assumptions.
|
||||
|
||||
For design documentation, please see the file "design.txt",
|
||||
and also, look at the header files carefully. The documentation
|
||||
for each routine is in the header files for that routine.
|
||||
For design documentation, please read our doxygen documentation.
|
||||
This can be found at https://code.gnucash.org/docs/STABLE/
|
||||
Alternatively you can build it yourself by running
|
||||
[ninja|make] doc
|
||||
The result will be found in
|
||||
{builddir}/libgnucash/doc/html/index.html
|
||||
|
||||
September 1998
|
||||
The same information can mostly be found directly in the header
|
||||
files in this directory as well (though in marked up source format).
|
||||
|
||||
@ -6,8 +6,45 @@ API: \ref KVP
|
||||
|
||||
This file documents the use of keys in the key-value pair system
|
||||
used by the GnuCash Application (both the engine, and non-engine, GUI
|
||||
pieces). Before assigning keys for use, please read the Key-Value
|
||||
Policy in the GnuCash Design Document located under src/doc/design.
|
||||
pieces).
|
||||
|
||||
\section kvppolicy KVP 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:
|
||||
|
||||
- This should be used to document the use of keys and values.
|
||||
Please consult it before planning any use of new keys.
|
||||
|
||||
- Key strings should be in all lower case with the '-' character
|
||||
separating words. If possible, use only alphanumeric characters and
|
||||
'-'. Example: `bank-info`. Because the '/' character is useful for
|
||||
describing keys in sub-frames (`bank-info/routing-number`), do not
|
||||
use the '/' character in key names.
|
||||
|
||||
- Favor longer, descriptive key strings over short ones. Example:
|
||||
`online-banking-info` is better than `onln-bnk`.
|
||||
|
||||
- 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.
|
||||
|
||||
- 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.
|
||||
|
||||
- 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.
|
||||
|
||||
\section kvpdocformat KVP Documentation format
|
||||
|
||||
The format of the data below is:
|
||||
|
||||
|
||||
@ -38,6 +38,5 @@ install(TARGETS gnc-module
|
||||
|
||||
install(FILES ${gnc_module_HEADERS} DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/gnucash)
|
||||
|
||||
set_local_dist(gnc_module_DIST_local CMakeLists.txt ${gnc_module_SOURCES} ${gnc_module_HEADERS}
|
||||
README)
|
||||
set_local_dist(gnc_module_DIST_local CMakeLists.txt ${gnc_module_SOURCES} ${gnc_module_HEADERS})
|
||||
set(gnc_module_DIST ${gnc_module_DIST_local} ${test_gnc_module_DIST} ${example_DIST} PARENT_SCOPE)
|
||||
|
||||
@ -1,6 +0,0 @@
|
||||
This is gnc-module, a plugin/module system for gnucash and related
|
||||
software. The documentation currently consists of 'doc/design.txt'.
|
||||
|
||||
Bill Gribble
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user