IntenseFinance/gnucash
3
0
Fork 0
mirror of https://github.com/Gnucash/gnucash.git synced 2026-09-03 20:53:02 -05:00
Code Issues Packages Projects Releases Wiki Activity

2001-05-09 Dave Peticolas <dave@krondo.com>

Browse Source 
* src/doc/design/user-preferences.texinfo: update docs

	* src/doc/design/reports.texinfo: update docs

	* src/doc/design/top-level.texinfo: update docs

	* src/doc/design/register.texinfo: update docs

	* src/doc/design/component-manager.texinfo: update docs


git-svn-id: svn+ssh://svn.gnucash.org/repo/gnucash/trunk@4139 57a11ea4-9604-0410-9ed3-97b8803252fd
This commit is contained in:
Dave Peticolas
2001-05-09 08:55:39 +00:00
parent 87edd32c82
commit f03fd6f8a1
9 changed files with 179 additions and 143 deletions
Download Patch File Download Diff File Expand all files Collapse all files
ChangeLog
+12
View File
@@ -1,3 +1,15 @@
2001-05-09 Dave Peticolas <dave@krondo.com>
* src/doc/design/user-preferences.texinfo: update docs
* src/doc/design/reports.texinfo: update docs
* src/doc/design/top-level.texinfo: update docs
* src/doc/design/register.texinfo: update docs
* src/doc/design/component-manager.texinfo: update docs
2001-05-09 Christian Stimming <stimming@tuhh.de>
* src/scm/report/price-scatter.scm: Added new option: get weighted
README.cvs
-1
View File
@@ -64,4 +64,3 @@ Owen Taylor.
Dave Peticolas
May 2, 2001
src/doc/design/component-manager.texinfo
+4
View File
@@ -336,6 +336,10 @@ 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
src/doc/design/engine.texinfo
+29 -31
View File
@@ -39,24 +39,24 @@ be created as a shared library for use by other programs.
Splits (@pxref{Splits}), or "Ledger Entries" are the fundamental
accounting units. Each Split consists of a quantity (number of dollar
bills, number of shares, etc.), the price of that quantity (the price of
one dollar is 1.00 dollars, etc.), 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}).
bills, number of shares, etc.), the value of that quantity expressed in
a (possibly) different currency than the quantity, 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, a number, a
list of one or more Splits, and a key-value frame. When double-entry
rules are enforced, the total value of the splits is zero. Note that if
rules are enforced, the total value of the splits is zero. Note that if
there is just one split, its value must be zero for double-entry
accounting; this used to be used for storing prices, but with the advent
of the pricedb, zero-valued splits are probably best avoided. If there
are two splits, then the value of one must be positive, the other
negative: this denotes that one account is credited, and another is
debited by an equal amount. Positive Split values are 'debits' and
negative Split values are 'credits'. Ensuring the Splits to 'add up' to
zero causes a double-entry accounting system to always balance.
of the Price DB, this is no longer the case. If there are 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. Positive Split values are 'debits' and negative Split values are
'credits'. Ensuring the Splits to 'add up' to zero causes a double-entry
accounting system to always balance.
The engine does not enforce double-entry accounting, but provides an API
to enable user-code to find unbalanced transactions and 'repair' them so
@@ -65,20 +65,19 @@ 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.
The conversion price is simply the price stored in the Split. This
feature allows currency-trading accounts to be established.
This feature allows currency-trading accounts to be established.
Every Split must point at its parent Transaction, and that Transaction
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
forced 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.
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 accouting practice. Each Account consists of a list of
as "Ledgers" in accounting practice. Each Account consists of a list of
Splits that debit that Account. To ensure consistency, if a Split points
at an Account, then the Account must point at the Split, and vice-versa.
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
@@ -1138,14 +1137,13 @@ is linked to.
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 blank, in which case shares are
Account, unless the security field is NULL, in which case shares are
given in units of the Account currency. @xref{Accounts}.
@item A 'price'
This represents the price of the shares. The price is a ratio of the
parent Account currency to the parent Account security. For most Accounts,
the security is blank, and thus the price is @code{1.0}, since the currency
effectively is the security. @xref{Accounts}.
@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.
@item A 'reconciled' flag
This flag represents the reconciled status of the Split. Possible
@@ -1231,12 +1229,12 @@ Return the 'share quantity' of @var{split}.
@end deftypefun
@deftypefun gnc_numeric xaccSplitGetSharePrice (Split * @var{split})
Return the 'share price' of @var{split}.
Return the 'share price' of @var{split}, which is the value
divided by the share quantity.
@end deftypefun
@deftypefun gnc_numeric xaccSplitGetValue (Split * @var{split})
Return the value of @var{split}, which is equal to the share quantity
multiplied by the share price.
Return the value of @var{split}.
@end deftypefun
@deftypefun gnc_numeric xaccSplitGetBaseValue (Split * @var{split}, const char * @var{base_currency})
@@ -1617,7 +1615,7 @@ Set the description field of @var{trans} to @var{desc}.
@tindex GNCBook
The @dfn{GNCBook} interface encapsulate all the information about a
gnucash dataset, including the methods used to read and write the
GnuCash dataset, including the methods used to read and write the
dataset to datastores. This class provides several important services:
@itemize
@@ -1663,7 +1661,7 @@ 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
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.
src/doc/design/gnucash-design.texinfo
+4
View File
@@ -155,6 +155,10 @@ Cells
* BasicCell::
Reports
* Creating a Report::
User Preferences
* Option Databases::
src/doc/design/register.texinfo
+29 -46
View File
@@ -4,7 +4,7 @@
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
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.
@@ -63,47 +63,27 @@ cells must implement. A BasicCell contains the following data members.
@item char *value
The 'value' of the cell stored as a character string.
@item guint8 input_output
This is a bit field used for storing flag values. The following flag
values are defined.
@item GdkWChar *w_value
The 'value' of the cell stores as a wide character string.
@table @code
@item XACC_CELL_ALLOW_INPUT
If set, the cell will may accept keyboard and mouse input from the
user. Otherwise, the cell is for display only.
@item XACC_CELL_ALLOW_SHADOW
If set, the cell will 'shadow' the contents of the register which it
is contained in. In other words, as the cell is moved to new locations,
the value of the register at that location will be copied into the cell.
@item XACC_CELL_ALLOW_EXACT_ONLY
If set, the cell may only be entered by 'exact' indication of the
user. Currently, this means the user must click on the cell with the
mouse. This flag will prevent the cell from being tabbed into.
@end table
@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).
@item guint32 bg_color
@itemx guint32 fg_color
An RGB value indicating the background (foreground) color to render the
cell with.
@item gboolean use_bg_color
@itemx gboolean use_fg_color
A boolean value indicating whether to use the @code{bg_color}
(@code{fg_color}) member.
@end table
@@ -112,9 +92,7 @@ A boolean value indicating whether to use the @code{bg_color}
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. It provides several functions.
First, it defines a tab-group (group of cells that can be traversed by
hitting the tab-key). More importantly, through the mechanism of Cursors
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
@@ -126,16 +104,16 @@ transaction-processing applications with two-phase commit requirements.
@section Table
The @dfn{Table} is a displayed matrix. The table is a complex object;
it is NOT merely a cellblock. The table provides all of the GUI
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. It defines 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.
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.
@@ -148,13 +126,18 @@ 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,
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
@@ -168,7 +151,7 @@ this implementation was created with the engine financial structures in
mind.
The second component (src/SplitLedger.[ch]) implements the full register
behavior 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.
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.
src/doc/design/reports.texinfo
+48 -32
View File
@@ -1,5 +1,38 @@
@node Reports, User Preferences, Register, Top
@chapter Reports
@cindex Reports
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
Create 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
@@ -11,9 +44,10 @@ and should have
as well as
@code{(gnc:depend "html-generator.scm")}
@code{(gnc:depend "report-html.scm")}
if you wish to use the html table generation facilities.
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}.
@@ -24,51 +58,33 @@ 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 like the following from
distinct arguments are recognised, as in the following from
the transaction report:
@example
(gnc:define-report
'version 1
'name (string-db 'lookup 'title)
'name (N_ "Transaction Report")
'options-generator trep-options-generator
'renderer gnc:trep-renderer)
'renderer trep-renderer)
@end example
@table @code
@item 'version
@item version
This is the version number of the report, which is currently ignored.
@item 'name
This is self-explanatory.
@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
@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
structure with the options for the report. The options interface is
currently not fully documented, but should be.
@item 'renderer
This is a function that takes one argument - a set of options that use
the options API. It returns a list, which either contains strings, or
lists which only contain strings or lists of the same type. When
flattened and concatenated these strings should form the HTML of the
report.
@item renderer
This is the function which renders the HTML.
@end table
To generate the HTML, you can write your own HTML generation code, or
use the functions in html-generator.scm. These are already quite well
documented in the source code itself. To use the HTML generation code,
you build a structure containing a list of report columns, and for each
column write functions that, given a report entry, generate the text for
the cell, as well as column headers and column totals. This interface
is quite likely to change.
At the moment, the only tools for collecting summary information are
@code{gnc:account-get-balance-interval} and
@code{gnc:group-get-balance-interval}. As we start to calculate more
sophisticated summary statistics (particularly for stock and investment
tracking), we will add to these. Extracting data from accounts is also
done directly ATM, but we shall soon use the Query API to do this. The
Query API therefore needs some user-level documentation as well.
src/doc/design/top-level.texinfo
+39 -26
View File
@@ -1,24 +1,24 @@
@node Top Level, Engine, Introduction, Top
@chapter Architectural Overview
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 done up in C,
some in scheme, and some with the
GUI designer tool glade @uref{glade.pn.org}.
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
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
@@ -41,9 +41,21 @@ queries can be combined using standard boolean operators.
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 being deprecated. A text-based
format using scheme forms is being developed as a replacement. This new
module will be separate from the Engine.
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
@@ -75,23 +87,23 @@ The @dfn{Reports} module (@file{src/scm/report.scm},
balance sheets, profit & loss statements, etc. by using the engine
API to fetch and display data formatted in HTML.
This module is being redesigned to use the Query API to fetch the engine
information instead of using the raw engine interface. The new reporting
design will use Queries to extract the data and assemble it into a
view-independent format. This data will then be converted to HTML
reports and/or graphs such as bar and pie charts.
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 will be a future module implementing GUI graphs
such as bar and pie charts. These graphs will be interactive in that the
user can, for example, move pie wedges, and 'live' in that the user will
be able to click on graph subsections to see a detail graph or report of
that particular subsection.
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 will be implemented using the GUPPI library being developed
by Jon Trowbridge (@url{http://www.gnome.org/guppi}).
This module is implemented using the GUPPI library being developed by
Jon Trowbridge (@url{http://www.gnome.org/guppi}).
@section Price Quotes
@@ -146,5 +158,6 @@ 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. The Qt code
won't compile, and most/all functions are missing.
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.
src/doc/design/user-preferences.texinfo
+14 -7
View File
@@ -3,17 +3,17 @@
@cindex User Preferences
The options system is used to obtain user preferences, both globally,
and when displaying a report. A wide variety of option types are
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.
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
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..
documented.
@menu
* Option Databases::
@@ -47,7 +47,7 @@ display.
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
accounts in the account hierachy, or even colors. GnuCash supports all
of these and more:
@table @code
@@ -96,6 +96,14 @@ or more items from the group.
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
@@ -256,7 +264,7 @@ for currency selection.
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.
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
@@ -291,4 +299,3 @@ type as how the default values are specified (except the date option
which needs to be fixed).
@end deffn