User:Yawaramin

GnuCash Scheme Report API

I'm trying to figure out the GnuCash API for reports by examining the GnuCash and Scheme module sources, report sources and the reports they produce one by one.

This document is mostly the result of my educated guesses. Everyone please feel free to change anything that's inaccurate, and move it to a more appropriate place if needed. I just started tonight (5 Sep 2009) so it's definitely a work in progress right now.

All identifiers are in alphabetical order ignoring case and non-alphanumeric characters in the names.

Defined Variables

---

gnc:pagename-accounts

The name of the accounts page (tab) in the options dialog box

gnc:pagename-general

The name of the general page (tab) in the options dialog box

Procedures

---

gnc-account-get-children

Returns: A list of immediate children accounts of the given account; not all descendents. For that, see gnc-account-get-descendants-sorted

Arguments:

• The account whose children we want

gnc-account-get-descendants-sorted

Returns: The descendants of the given account

Arguments:

• The account whose descendants we want

gnc-account-get-full-name

Returns: The full name of an account

Arguments:

• An Account object

gncAccountGetGUID

Returns: The GUID of an account

Arguments:

• An Account object

gnc:accounts-count-splits

Returns: The number of splits across all the given accounts

Arguments:

• List of account objects

gnc:accounts-get-all-subaccounts

Returns: List of subaccounts of an account

Arguments:

• An Account object

gnc:case-exchange-fn

Returns: A currency exchange calculator function

Arguments:

• A price source
• The report currency
• The date at which we want to calculate the exchange values

gnc:date-option-absolute-time

Converts a date option value to absolute Unix epoch time

Returns: A date/time object in absolute time (i.e. from the start of the Unix epoch)

Arguments:

• A date option

gnc:filter-accountlist-type

Returns: A list of accounts filtered by their type

Arguments:

• A list of account types to filter by. Accepts, among others: ACCT-TYPE-BANK

ACCT-TYPE-CASH ACCT-TYPE-ASSET ACCT-TYPE-STOCK ACCT-TYPE-MUTUAL

• A list of accounts

gnc-get-current-root-account

Returns: The root account of the book that is currently open

gnc:gnc-monetary-amount

Returns: The amount of a Gnc-Monetary object

Arguments:

• A Gnc-Monetary object. These can be created with gnc:make-gnc-monetary

Defined in: src/engine/gnc-numeric.scm

gnc:html-document-set-title!

Arguments:

• The HTML document object
• String to set as the document title

gnc:lookup-option

Returns: The actual option object (not its value)

Arguments:

• Options object. Can be specified with the gnc:report-options procedure
• Name of page (tab) where the option lives
• Name of the option to look up

gnc:make-commodity-collector

Returns: A commodity collector object. (TODO Explain what this is)

gnc:make-gnc-monetary

Returns: A Gnc-Monetary object, which is a structure consisting of an amount of money and its currency

Arguments:

• A Currency object
• An amount

Defined in: src/engine/gnc-numeric.scm

gnc:make-html-document

Returns: An HTML document object

gnc:make-html-table

Returns: An HTML table object

gnc:make-html-text

Returns: An HTML text object

gnc:make-simple-boolean-option

Creates a checkbox control for yes/no options

Returns: The boolean option object

Arguments:

• Options dialog box tab (page) name where the option lives
• Label for the control
• Order in which the option appears on the page. Can be text from `a' to `z'
• Tooltip for the checkbox control
• Default value

gnc:new-options

Returns: A new Options object. An Options object is a database of user-settable options and their values

gnc:option-value

Returns: The value of the given option

Arguments:

• The option object whose value to get. Can be specified with the gnc:lookup-option procedure

gnc:options-add-account-selection!

Adds a control that allows user to select multiple accounts from the tree of accounts

Arguments:

• Options object
• Options dialog box tab (page) name where the option lives
• Label for the control that sets how many levels of accounts to show
• Label for the control that sets whether to show subaccounts
• Label for the overall control
• Order in which the option appears on the page. Can be text from `a' to `z'
• (TODO Probably the default account display depth)
• A lambda expr that returns a list of accounts to show at first
• (TODO Don't know but set to #f)

gnc:options-add-currency!

Adds a currency selector control to the options dialog box

Arguments:

• Options object
• Options dialog box tab (page) name where the option lives
• Text to use for option label
• Order in which the option appears on the page. Can be text from `a' to `z'

gnc:options-add-date-interval!

Adds a date interval selector control to the options dialog box

Arguments:

• Options object
• Options dialog box tab (page) name where the date option lives
• Text to use to label `From' part of interval
• Text to use to label `To' part of interval
• Order in which the option appears on the page. Can be text from `a' to `z'

gnc:options-add-price-source!

Adds a price source selector option to the options dialog box

Arguments:

• Options object
• Options dialog box tab (page) name where the option lives
• Text to use for option label
• Order in which the option appears on the page. Can be text from `a' to `z'
• Symbol which names the price database to use. E.g. the symbol corresponding

to the `Nearest in time' option is 'pricedb-nearest

gnc:options-set-default-section

Sets the options dialog box tab to show when the dialog box appears

Arguments:

• Options object
• Options dialog box tab (page) name to set as the default

gnc-print-date

Returns: A formatted date string

Arguments:

• A date/time object

gnc:register-option

Arguments:

• Options object
• An individual option object, e.g. made with gnc:make-simple-boolean-option

gnc:report-options

Returns: Options object for the report

Arguments:

• Report object

gnc:report-percent-done

Updates the progress bar at the bottom of the screen which shows report creation progress

Arguments:

• A percentage value indicating how much of the report has been done so far

gnc:report-starting

(TODO Probably marks the starting point of the report rendering. Probably used to start the progress bar when a report is (re)loaded)

Arguments:

• Name of the report

gncSplitGetGUID

Returns: The GUID of a split

Arguments:

• A Split object

gnc:timepair-end-day-time

Returns: The Timepair object supplied as the argument but with its time set to the last second of its day.

Arguments:

• A Timepair object. Can come from the gnc:date-option-absolute-time procedure

Defined in: src/app-utils/date-utilities.scm

gnc:timepair-le

Returns: Boolean indicating whether the first Timepair is earlier than or the same as the second Timepair

Arguments:

• A Timepair object
• A Timepair object

Defined in: src/app-utils/date-utilities.scm

gnc:timepair-start-day-time

Returns: The Timepair object supplied as the argument but with its time set to the first second of its day.

Arguments:

• A Timepair object. Can come from the gnc:date-option-absolute-time procedure

Defined in: src/app-utils/date-utilities.scm

xaccAccountGetCommodity

Returns: The commodity (usually the currency, sometimes the fund name) of an account

Arguments:

• An Account object

xaccAccountGetName

Returns: The name of the account

Arguments:

• An Account object

xaccAccountGetSplitList

Returns: A list of the splits in an account

Arguments:

• An Account object

xaccSplitGetParent

Returns: The parent (TODO account? transaction?) of a split

Arguments:

• A Split object