diff --git a/ChangeLog b/ChangeLog index 28614a6379..523ca14067 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,17 @@ +2001-05-16 Dave Peticolas + + * src/doc/design/gnucash-design.texinfo: update docs + + * src/doc/design/engine.texinfo: update docs + + * src/engine/Account.c (xaccCloneAccountSimple): remove + redundant initialization + (xaccAccountGetSlots): handle NULL + + * src/engine/Account.h: fix docs + + * src/engine/AccountP.h: fix spelling errors in comments + 2001-05-16 Robert Graham Merkel * src/scm/html-utilities.scm ((gnc:html-make-empty-data-warning)): @@ -123,12 +137,13 @@ 2001-05-15 Robert Graham Merkel - * doc/sgml/C/xacc-reports.sgml, xacc-about.sgml, xacc-dateinput.sgml, - xacc-account-summary.sgml, xacc-balancesheet.sgml, xacc-common-report-options.sgml + * doc/sgml/C/xacc-reports.sgml, xacc-about.sgml, + xacc-dateinput.sgml, xacc-account-summary.sgml, + xacc-balancesheet.sgml, xacc-common-report-options.sgml xacc-mainwin.sgml: update documentation for new features. - * doc/sgml/C/xacc-asset-liability-barcharts.sgml: new file. Placeholder - at this stage. + * doc/sgml/C/xacc-asset-liability-barcharts.sgml: new file. + Placeholder at this stage. * doc/sgml/C/xacc-asset-liability-piecharts.sgml, xacc-gnome-mdi.sgml, xacc-income-expense-barcharts.sgml, xacc-income-expense-piecharts.sgml, diff --git a/src/doc/design/engine.texinfo b/src/doc/design/engine.texinfo index 6fa7ddb185..7fb049e30f 100644 --- a/src/doc/design/engine.texinfo +++ b/src/doc/design/engine.texinfo @@ -258,7 +258,7 @@ directly. Example: account = < something to get an Account pointer > - saved_guid = *xaccAccountGetGuid(account); + saved_guid = *xaccAccountGetGUID(account); ... @@ -1537,12 +1537,6 @@ for editing. Allocate, initialize, and return a new Transaction. @end deftypefun -@deftypefun void xaccTransAppendSplit (Transaction * @var{trans}, Split * @var{split}) -Append @var{split} to the collection of Splits in @var{trans}. If the -Split is already a part of another Transaction, it will be removed from -that Transaction first. -@end deftypefun - @deftypefun void xaccTransDestroy (Transaction * {trans}) Remove all of the Splits from each of their accounts and free the memory associated with them. This routine must be followed by either an @@ -1551,6 +1545,12 @@ be freed, or by @code{xaccTransRollbackEdit()}, in which case all the original Splits are put back into place. @end deftypefun +@deftypefun void xaccTransAppendSplit (Transaction * @var{trans}, Split * @var{split}) +Append @var{split} to the collection of Splits in @var{trans}. If the +Split is already a part of another Transaction, it will be removed from +that Transaction first. +@end deftypefun + @deftypefun void xaccTransBeginEdit (Transaction * @var{trans}) This method must be called before any changes are made to @var{trans} or any of its component Splits. If this is not done, errors will result. @@ -1694,9 +1694,19 @@ contain the following pieces of information: The list of debits and credits which apply to the Account. The sum of all debits and credits is the account balance. +@item A type +An integer code identifying the type of account. The Account type +determines whether the Account holds shares valued in a currency +or not. It is also used by the GUI and reporting system to determine +how debits & credits to the Account should be treated and displayed. + @item A name The name of the Account. +@item An account code +A string that is intended to hold a unique user-selected identifier +for the account. However, uniqueness of this field is not enforced. + @item A description A textual description of the Account. @@ -1704,6 +1714,10 @@ A textual description of the Account. The commodity that Splits in the account are valued in, i.e., the denomination of the 'value' member of Splits in the account. +@item A curreny SCU +The SCU is the smallest convertible unit that the currency is +traded in. This value overrides the default SCU of the currency. + @item A security For Accounts which may contain shares (such as stock accounts), the denomination of the 'share quantity' member of Splits in @@ -1711,10 +1725,135 @@ the accounts. For accounts which do not contain shares, the security is blank, and the share quantities are denominated in the Account currency. +@item A security SCU +Analogous to the currency SCU, but for the security. + +@item A parent and child Account Group. +The parent and child of an Account are Account Groups +(@pxref{Account Groups}). Account Groups are used to +connect Accounts together into an Account hierarchy. +If the parent Account Group is not present, the Account +is at the top level of the hierarchy. If the child +Account Group is not present, the Account has no +children. + @end table In addition to the above, Accounts contain a key-value pair frame. +@menu +* Account Types:: +* General Account API:: +@end menu + + +@node Account Types, General Account API, Accounts, Accounts +@subsection Account Types +@tindex GNCAccountType + +Account Types are defined by the @code{GNCAccountType} enumeration. +Possible values are: + + @table @code + + @item BAD_TYPE, NO_TYPE + Both of these values indicate an illegal Account type. + + @item BANK + Denotes a savings or checking account held at a bank. + Such an account is often interest bearing. + + @item CASH + Denotes a shoe-box or pillowcase stuffed with cash. In other + words, actual currency held by the user. + + @item CREDIT + Denotes credit card accounts. + + @item ASSET + Denotes a generic asset account. + + + @item LIABILITY + Denotes a generic liability account. + + @item STOCK + A stock account containing stock shares. + + @item MUTUAL + A mutual fund account containing fund shares. + + @item CURRENCY + Denotes a currency trading account. In many ways, a currency trading + account is like a stock trading account, where both quantities + and prices are set. However, generally both currency and security + are national currencies. + + @item INCOME + Denotes an income account. The GnuCash financial model does not + use 'categories'. Actual accounts are used instead. + + @item EXPENSE + Denotes an expense account. + + @item EQUITY = 10, + Denotes an equity account. + + @end table + + +@node General Account API, , Account Types, Accounts +@subsection General Account API + +@deftypefun {Account *} xaccMallocAccount (void) +Allocate and initialize an Account. The account must be +destroyed by calling @code{xaccAccountBeginEdit} followed +by @code{xaccAccountDestroy}. +@end deftypefun + +@deftypefun void xaccAccountDestroy (Account * @var{account}) +Destroys @var{account} and frees all memory associated with +it. This routine will also destroy the Account's children. +You must call @code{xaccAccountBeginEdit} before calling +this function. +@end deftypefun + +@deftypefun void xaccAccountBeginEdit (Account * @var{account}) +This routine, together with @code{xaccAccountCommitEdit}, +provide a two-phase-commit wrapper for account updates +much in the same way as @var{xaccTransBeginEdit} and +@var{xaccTransCommitEdit} do for Transactions. +@end deftypefun + +@deftypefun void xaccAccountCommitEdit (Account * @var{account}) +The counterpart to @var{xaccAccountBeginEdit}. +@end deftypefun + +@deftypefun {Account *} xaccCloneAccountSimple(const Account * @var{from}) +Return a 'copy' of @var{from} that is identical in the type, name, code, +description, kvp data, and currency. All other fields are the same as an +account returned by @code{xaccMallocAccount}. +@end deftypefun + +@deftypefun {const GUID *} xaccAccountGetGUID (Account * @var{account}) +Return the globally unique id associated with @var{account}. +@end deftypefun + +@deftypefun {Account *} xaccAccountLookup (const GUID * @var{guid}) +Return the Account associated with @var{guid}, or NULL if there is +no such Account. +@end deftypefun + +@deftypefun {kvp_frame *} xaccAccountGetSlots (Account * @var{account}) +Return the @code{kvp_frame} associated with @var{account}. User code +may modify this @code{kvp_frame}, but must not destroy it. +@end deftypefun + +@deftypefun void xaccAccountSetSlots_nc (Account * @var{account}, kvp_frame * @var{frame}) +Set the @code{kvp_frame} associated wih @var{account}. After the call, +@var{frame} is owned by @var{account}, so don't destroy it. +@end deftypefun + @node Account Groups, GNCBooks, Accounts, Engine @section Account Groups diff --git a/src/doc/design/gnucash-design.texinfo b/src/doc/design/gnucash-design.texinfo index cfea498740..ea546b3ee8 100644 --- a/src/doc/design/gnucash-design.texinfo +++ b/src/doc/design/gnucash-design.texinfo @@ -130,12 +130,17 @@ Splits * Split Getters:: * Split Setters:: -The Transaction Edit Cycle +Transactions * General Transaction API:: * Transaction Getters:: * Transaction Setters:: +Accounts + +* Account Types:: +* General Account API:: + GNCBooks * GNCBook API:: diff --git a/src/engine/Account.c b/src/engine/Account.c index 7861bb1ea0..3cc15740fa 100644 --- a/src/engine/Account.c +++ b/src/engine/Account.c @@ -141,8 +141,7 @@ xaccCloneAccountSimple(const Account *from) Account *ret; ret = xaccMallocAccount(); - xaccInitAccount(ret); - + ret->type = from->type; ret->accountName = g_strdup(from->accountName); @@ -476,6 +475,7 @@ xaccAccountBringUpToDate(Account *acc) kvp_frame * xaccAccountGetSlots(Account * account) { + if (!account) return NULL; return(account->kvp_data); } diff --git a/src/engine/Account.h b/src/engine/Account.h index 5023e831e2..cf6be7bfee 100644 --- a/src/engine/Account.h +++ b/src/engine/Account.h @@ -81,16 +81,13 @@ typedef enum CURRENCY = 7, /* The currency account type indicates that the account is a * currency trading account. In many ways, a currency trading - * account is like a stock trading account, where both quantities - * and prices are set. + * account is like a stock trading account, where both values + * and share quantities are set. */ INCOME = 8, EXPENSE = 9, - /* Income and expense accounts are used to denote income and expenses. - * Thus, when data in these accountsare displayed, the sign of the - * splits (entries) must be reversed. - */ + /* Income and expense accounts are used to denote income and expenses. */ EQUITY = 10, /* Equity account is used to balance the balance sheet. */ @@ -122,14 +119,14 @@ gboolean xaccAccountEqual(Account *a, Account* b, gboolean check_guids); /* * The xaccAccountBeginEdit() and xaccAccountCommitEdit() subroutines * provide a two-phase-commit wrapper for account updates. - * They are incompletely implemented .... + * They are incompletely implemented. * * The xaccAccountDestroy() routine can be used to get rid of an * account. The account should have been opened for editing * (by calling xaccAccountBeginEdit()) before calling this routine. */ -Account *xaccMallocAccount (void); -Account * xaccCloneAccountSimple(const Account *from); +Account * xaccMallocAccount (void); +Account * xaccCloneAccountSimple(const Account *from); void xaccAccountBeginEdit (Account *account); void xaccAccountCommitEdit (Account *account); void xaccAccountDestroy (Account *account); @@ -140,8 +137,6 @@ void xaccAccountSetSlots_nc(Account *account, kvp_frame *frame); /* * The xaccAccountGetGUID() subroutine will return the * globally unique id associated with that account. - * User code should use this id to reference accounts - * and *not* the integer account id below. * * The xaccAccountLookup() subroutine will return the * account associated with the given id, or NULL @@ -222,7 +217,7 @@ void xaccAccountSetCommodity (Account *account, gnc_commodity *comm); * The future API will associate only one thing with an account: * the 'commodity'. Use xaccAccountGetCommodity() to fetch it. */ -/* these two funcs take control of thier gnc_commodity args. Don't free */ +/* these two funcs take control of their gnc_commodity args. Don't free */ void xaccAccountSetCurrency (Account *account, gnc_commodity *currency); void xaccAccountSetSecurity (Account *account, gnc_commodity *security); void xaccAccountSetCurrencySCU (Account *account, int frac); diff --git a/src/engine/AccountP.h b/src/engine/AccountP.h index d61e9d613f..63a6a681d6 100644 --- a/src/engine/AccountP.h +++ b/src/engine/AccountP.h @@ -57,23 +57,23 @@ struct _account { /* public data, describes account */ GUID guid; /* globally unique account id */ - /* The accountName is an arbitrary string assinged by the user. + /* The accountName is an arbitrary string assigned by the user. * It is intended to a short, 5 to 30 character long string that - * is displayed by the GUI as the account mnomenic. + * is displayed by the GUI as the account mnemonic. */ char *accountName; - /* The accountCode is an arbitary string assigned by the user. + /* The accountCode is an arbitrary string assigned by the user. * It is intended to be reporting code that is a synonym for the - * accountName. Typically, it will be a numeric value tht follows + * accountName. Typically, it will be a numeric value that follows * the numbering assignments commonly used by accountants, such * as 100, 200 or 600 for top-level * accounts, and 101, 102.. etc. * for detail accounts. */ char *accountCode; - /* The description is an arbitraary string assigned by the user. - * It is intended to be a longer, 1-5 sentance description of what + /* The description is an arbitrary string assigned by the user. + * It is intended to be a longer, 1-5 sentence description of what * this account is all about. */ char *description;