Using QHacc

QHacc was designed to be as simple and straightforward as possible. It utilizes popups, pulldowns (and other randy-sounding things), keyboard commands, highlighting, and bold fonts to help you organize your finances easily.

Environment Variables

QHacc utilizes a few environmental variables to get itself going. For the most part, QHacc doesn't need any of these environment variables to operate, but they are useful. The variables are:

Command-Line Interface

QHacc is meant to be used interactively from a graphical display. That interface will be used the most by far. However, QHacc has several command-line options. Some of these options can control or modify QHacc's GUI interface, but many are meant to be used when starting a GUI is not possible or unnecessary. Below is a table of QHacc's command-line options.
OptionArgumentsDescription
-f or --home QHACC_HOME1 Using this switch will override whatever value is currently stored in the QHACC_HOME environment variable, if any. This options allows multiple QHACC_HOMEs to be used for different purposes.
-w or --warranty none show warranty information
-l QHACC_LANGDIR Using this switch will point to a non-default language file for i18n support.
--debug debug level (0-6) set runtime debugging information level
--cron2 scheduled transaction filename see Scheduled Transactions below
--archive2 a date string3, or account identifier4 see Archiving below
--restore archive file see Archiving below
--preport account identifier4 "Totals by Payee" report. seeReporting below
--breport account identifier4 "Monthly Balances" report. seeReporting below
--dreport account identifier4 "Monthly Deltas" report. seeReporting below
--areport account identifier4 "Averages" report. seeReporting below
--budget account identifier4 "Budget" report. seeReporting below
--journal ledger identifier5 "Journal" report. seeReporting below
--accounts none display account names, balances, and number of transactions
--transactions account identifier4 display all the transactions in a particular account
--import QHACC_HOME1 import data from the given QHACC_HOME into the current QHACC_HOME
--export QHACC_HOME1 export the current data to the given QHACC_HOME location
--create QHACC_HOME1 display commands for creating a functional QHACC_HOME from scratch
--reconcile QHACC_HOME1 reconcile all transactions that are duplicated in the given QHACC_HOME
--verifydb none verify that QHacc's database is in a consistent state
--fixdb none make QHacc's database consistent
--plugins none display the information about the available plugins
--help none show these options
Notes:
1: valid QHACC_HOMEs are determined from the plugins available to the QHacc engine. Generally, these are identified by <plugin identifier;>:<home string>
2: if --cron and --archive are both specified, they will be executed in the order given on the command line.
3: the user-supplied date string must be consistent with the date format specified in the user
preferences dialog. That is, if you normally use the European format and '-' as the separator, and you are currently in the QHACC_HOME directory, the command: qhacc --archive 29-02-2000 would archive all transactions before 1 March, 2000.
4: an account identifier can be the account's full name, the account's short name, or the account's ID. The user-supplied names are checked in that order.
5: a ledger identifier can be the ledger's name or numeric ID. The user-supplied names are checked in that order.

QHACC_HOME

Before running QHacc, the program must know where it is going to save files, and where to look for already-saved ones. It does this through the use of the QHACC_HOME environment variable. This is usually set before running QHacc, but it can be passed via the command line with the -f option. By default, QHacc will assumes the QHACC_HOME is located in a local directory, but various plugins can override that assumption. Regardless of where QHACC_HOME is, QHacc will only write data into that location. It will not create that location for you if it doesn't exist.

Local Files

"Out of the box," QHacc only supports writing to a directory on the local filesystem. In this case, QHacc will look into the specified directory for all its files. In addition, when saving files, it will change their permissions so that only the user running QHacc can open them later. This avoids having possibly sensitive information available to anyone on the system. If you really, really know what you are doing, you can set the "KEEPFILEPERMS" preference manually to keep QHacc from changing its files' permissions. This is highly discouraged.

Multiple Personalities

QHacc keeps all the information about a set of accounts in QHACC_HOME, but it also allows a user to switch QHACC_HOME during execution. This functionality may be useful if, for example, a user has a set of business accounts in addition to a set of personal accounts, and wishes to keep both sets exclusive. Thus, each QHACC_HOME can be thought of as a different personality. When requested to switch personalities, QHacc closes the old set of accounts without saving them and then opens the new set of accounts.

Interface Layout

The QHacc window consists of just three main parts: the Account Chooser, the Account Viewer, and the Status Bar. The Account Chooser starts on the left side of the screen, and displays all your accounts and their balances. The rest of the screen is devoted to the Account Viewer. The Account Viewer displays all the transactions in a specific account. The Status Bar runs below the Account Viewer and the Account Chooser. It displays information about the currently-opened account such as it name, type of account, number of transactions, and account balance. It also notifies the user if any information has been changed since the last save.

The Account Chooser

The Account Chooser is the navigator and maintenance hub for accounts. Clicking on an account will open that account, and display all its transactions in the Account Viewer. Double-clicking on an account will bring up the Account Edit Dialog box. More about that later.

If you are not using a mouse, the Account Chooser is navigable with the up and down arrows. Pressing the spacebar will open the account.

In both cases, the selected account will be printed in bold font and a colored highlight bar will illuminate the account in the Chooser.

The popup menu available in the Account Chooser allows you to reconcile, edit, add, or delete an account. It is not necessary to open an account in order to use these functions. (i.e., You can be viewing your checking account, and open your savings account for reconciling.) Please be careful when using this liberty to make sure you don't delete the wrong account. The popup also allows you to toggle the Account Chooser's view, to show or hide categories. If you are not using a mouse, these functions are available from the Account or Preferences menubar.

The Account Viewer

The Account Viewer displays all the transactions in the opened account. It looks vaguely like a spreadsheet display, with serveral columns and resizeable column headers. Underneath the headers are all the transactions in the account. Clicking on a transaction will open the Transaction Editor. Alternately, you can click on the "<new>" transaction to insert a totally new transaction. Alternately alternately, you can use the keyboard to navigate the Viewer. Using the up and down arrows will select transactions. As with the Account Chooser, pressing the spacebar will open the transaction for editing.

The Account Viewer window has a popup menu to work on the transactions in the viewer. There are standard functions like add, reconcile, and memorize. Please see the section below for more details on memorizing transactions.

The Viewer and Chooser can be sorted on any column. Clicking on a column header sorts the data on that field. Clicking on the same field resorts the column in reverse order. Unlike previous versions of QHacc, these preferences are saved for future use.

Keyboard Shortcuts

QHacc was designed to be usable with or without a mouse. As a result, there are a number of keyboard shortcuts that are available. Some shortcuts are available when the Chooser has focus, and others are available when the Viewer is the focused object. Still others are available globally. The table below summarizes the keyboard shortcuts available in QHacc.
KeyScopeFunction
CTRL-S Global Save files.
CTRL-H Global Change QHacc Home
CTRL-T Global Save files and exit QHacc.
CTRL-Q Global Quit QHacc without saving files.
CTRL-V Global Toggle category view of account chooser.
CTRL-B Global Open a subset of transactions for the highlighted account.
CTRL-R Global Open a reconcile window for the highlighted account.
CTRL-L Global Toggle the reconcile balance display in status bar.
CTRL-N Global Create a new account.
CTRL-E Global Open the Account Editor dialog.
CTRL-SHIFT-X Global Delete the highlighted account.
CTRL-G Global Open the Graphing dialog.
CTRL-Y Global Open the Reporting dialog.
CTRL-F Global Open the Preferences dialog.
CTRL-W Global, if a transaction is hilighted in the Viewer Write the hilighted transaction to a schedule file.
spacebar Chooser Open the hilighted account in the Viewer.
del Chooser Delete the account hilighted in bold.
del Viewer Delete the transaction hilighted in bold.
CTRL-C Viewer Copy the hilighted transaction.
CTRL-P Viewer Paste the previously-copied transaction.
CTRL-X Global Cut the highlighted transaction.
i Viewer Insert a transaction. This new transaction will have the same date as the previously-hilighted transaction.
e Viewer Edit the hilighted transaction.
spacebar Viewer Open the Transaction Editor for the hilighted transaction.
spacebar Reconcile Window Mark the hilighted transaction as reconciled.

Creating an Account

The account is the central object in the QHacc engine. All transactions must be part of at least one account to be displayed. That said, creating an account is a painless process. You can either right-click in the Account Chooser and select "new account" from the pulldown, or choose "Create" from the Account menubar. From that dialog, you can enter the specifics of the account like opening balance or institution contact information. You can also specify a parent account to further categorize transactions. There are several types of accounts in QHacc:
ASSET
LIABILITY
EQUITY
EXPENSE
REVENUE
Note: The MARKET account type has been removed from QHacc version 2.0. Market accounts from previous versions will be upgraded to Equity accounts, and their transactions upgraded to regular transactions. Support for Market transactions may be added at a later date.

You can get more information about how to use these accounts in the Accounting Primer.

Accounts can also be made into categories. A category is an account in every sense of the word, but just a little different. Categories are not included when computing a personalities' total equity. There is also a preference item to exclude Categories from the Account Chooser. This preference is available through the Preferences Dialog or the Chooser's popup. This feature allows a user to maintain a eyeball on those accounts that are most important to him/her, while hiding the ones that are less important.

Transaction Operations

QHacc has a number of different types of transactions. They all work in the same way, so using them is easy. All transactions have five main fields:

Normal Transactions

If you use single-entry bookkeeping, most of the transactions you will probably enter into QHacc will be classified as normal transactions. They contain only the fields listed above. As described above, clicking on the "<new>" part of the Account Viewer is the usual way to enter a new transaction. An opened transaction can be saved by hitting the enter key. The changes can be discarded by pressing esc.

Market Transactions

As of v2.0, QHacc does not support market transactions. Support may be readded at a later date. However, any market transactions you currently have added in QHacc will be upgraded safely.

Split/Double-Entry Transactions

Split and Double-Entry transactions are handled the same way in QHacc. In order to use this transaction type, you must specify double entry bookkeeping from the Preferences Dialog.

Double-Entry transactions are just like single-entry transactions, except that each transaction must be part of two accounts. Double-Entry transactions are generally split between an income and expense account, though this rule is not a requirement. In any event, when you specify double entry bookkeeping, the Transaction Editor will get one more field--the double entry account field.

Split Transactions are a special type of transaction where one transaction has many different double-entry pairs. The most common use of this type of transaction is probably for entering your paycheck, I think. Your employer generally pays you one sum, but also pays taxes on your behalf, or splits your paycheck between several different accounts, like a checking and savings account. All these splits can be entered into a different account, but still only take up one transaction in your "job" account, for example. Is that clear?

In order to change a regular double-entry transaction into a good old-fashioned split transaction, one just needs to push the "split" button in the Transaction Editor. This will open the Split Editor, and you can go merrily on your way. If, on the other hand, you have a split transaction that you would like to make into a double-entry transaction, set its sum to "0" or just leave the appropriate sum field blank. When the transaction is saved, splits with 0 balance will be removed.

When using the Split Editor, it is important to remember that transactions are not modified until the Enter key or the "Enter" button is pressed. When the "Okay" button is pressed in the Split Editor, the transaction editor will display updated values, but the transaction is not modified. Opening the Split Editor again will display only the updated values. To get back to the original values of the transaction, hit "Cancel" in the Split Editor. This will reset all the splits to the transaction's original values.

Memorized Transactions

Memorized Transactions are a feature of QHacc aimed at reducing the number of times you must enter the same transaction. If you have a transaction that you enter into an account regularly (or just often), you can memorize it. From the transaction popup, select "memorize." Then, you can re-enter the same transaction as often as you like by selecting it from the "memorized" part of the popup. Everytime you enter a memorized transaction, the new one will be identical to the old one, except for the date. the date of the new transaction will be the same as the hilighted transaction at the time of insertion. This feature works for normal, market, double-entry, and split transactions, so use it 'til your heart's content.

To remove a transaction from the "memorized" list, select it from the "unmemorize" part of the popup.

QHacc supports copying and pasting transactions as well. The mechanism is exactly the same as for memorized transactions, but the only one transaction can be pasted at a time. Ctrl-C and Ctrl-P are the cut and paste shortcuts, respectively.

Scheduled Transactions

Scheduled transactions are the only type of transaction that QHacc cannot insert from the GUI. In fact, QHacc has no native scheduling facility at all, so scheduled transactions are not really scheduled by QHacc. Instead, scheduled transactions can be inserted into QHacc's database by creating a file in a particular format (see schedule format), and running QHacc from cron with the --cron argument and filename. The --cron argument is a shorthand way of calling the CRON import filter, which starts the command line version of QHacc and enters a single transaction before saving everything and exiting. In this mode, errors are written to standard error, but nothing else is written to the screen. The necessary transaction file can be written by hand, or created for you by QHacc from a transaction already entered. To have QHacc generate the file, just highlight the file in the account viewer, and select "write to trans" from the pulldown or press CTRL-W on the keyboard.

In addition to scheduling a flat dollar value when using scheduled transactions, QHacc supports scheduled transactions whose sum is based on a percentage of the account's balance at the time of entry. See the schedule format section of the manual for details.

Reconciling

Reconciling is one of the most important functions of any accounting program. It is the way to compare your balance to your bank's balance. In QHacc, you can open a reconcile window by right-clicking "reconcile" from either the Account Chooser popup or the Account pulldown. The reconcile window allows you to enter the ending date and ending balance for the account. When opening the window, the current date and current balance of the account are pre-entered in their respective fields. Changing the date will recalculate the expected balance. The reconcile window has a Account Viewer as well, but selecting a transaction will simply mark it as reconciled, and not open it for editing.

The reconcile window is a fully-capable Account Viewer. That is, transactions can be added, removed, or edited just as they can be in the main Account Viewer. Both displays will remain synchronized while the reconcile window is open. Any transactions added while the reconcile window is open will automatically be marked as reconciled, regardless of which display is used to enter it. The reconcile window is modeless, so several accounts be reconciled at once.

Reconciling from the command line is also supported. Running qhacc with the --reconcile argument will compare the given QHACC_HOME's data with the already-loaded data and reconcile any duplicate transactions. A transaction is determined to be duplicated if the date and sum are identical. Also see the plugins section, below.

Archiving and Restoring

QHacc provides a method for clearing out old transactions from accounts. The mode is similar to the --cron mode (above). This mode can be entered from by specifying --archive on the command line. The --archive argument must be followed by an account identifier or the date of the last transaction to prune. Account names are matched first, so if your account name happens to be the same as a valid datestring, the account will get archived. Why you would ever be in this situation is beyond me. In any event, the archived transactions are put in the QHACC_HOME directory, in a datestamped file. If an account is archived, it is removed from the Chooser display. In this mode, just like --cron mode errors are written to standard error, but nothing else is written to the screen.

The opposite of --archive is --restore. It must be followed by the filename from which to read the archived transactions. If a transaction references an archived account, that account is also restored.

Archiving and restoring files usually alters the accounts so that the current balance is consistent before and after archiving or restoring, but this behavior is customizable.

Exporting and Importing

Besides archiving and restoring transactions, QHacc provides a means of transferring data between QHACC_HOMEs. That mechanism is the --export and --import command line options. Both options take a QHACC_HOME argument to operate. When exporting, the entire contents of the current QHACC_HOME are dumped into the given QHACC_HOME. When importing, the entire contents of the given QHACC_HOME are merged with the current QHACC_HOME. This merge tries to avoid duplicate transactions, and is quite a bit more stringent in finding duplicates than --import (above). For example, for two transactions to be determined to be duplicates, they must have the same date, payee, sum, and parent account. Accounts are merged by name. Any unique data is merged with the old data. See the plugins section, below, for more functionality.

Plugins

As of version 2.8, QHacc has started using plugins to provide increased functionality. At the moment, this functionality is limited to the reading and writing of data to a QHACC_HOME. Still, this architecture extends the possible functionality of QHacc immensly.

The scheme is simple: every plugin has an identifier that tells the QHacc engine what data it expects to see. To use a plugin, just give QHacc the identifier as part of the QHACC_HOME. For example, if I want to have QHacc export its data in XML instead of its native format, I just run qhacc --export XML:<QHACC_HOME>. If I then want to import it into an empty MySQL database structure, I run qhacc -f MYSQL:<QHACC_HOME> --import XML:<export>.

There is even one plugin, which I like to call "The Cliimp," which basically supplants the --cron option for the command line. It allows a user to enter transactions interactively from the command line, thus making the GUI unnecessary. In the future, there will likely be more additions to this type of functionality.

For the memory conscious, it should be noted that plugins are not actually loaded until they are used. When QHacc first starts, it cycles through the plugin directories to figure out what plugins are available, but then doesn't load any until they are specifically called for. The goal for plugins was to have as much functionality as possible without increasing the memory requirements of the project.

Reporting

QHacc supports limited reporting from the GUI and the command line. The reports are available through the Graphs menu, or in the popup of the Account Chooser. The Report Dialog allows for reports from any date range and for any account or group of accounts. From the command line, the reports are slightly more restricted. Date ranges are not supported from the command line, though a dedicated user can create similar functionalty by creatively using the archive and restore functionailty in combination with the reports. In any event, the reports can be accessed from the command line using the --breport, --dreport, --areport, and --preport options followed by the account identifier. The Journal report is also available via the journal command line switch. This report shows each transaction entered in QHacc and its changes to its constituent accounts.

Some graphs allow expanded viewing via "click-throughs." Clicking on a section of the graph will open a subset view of the given account for the appropriate month. The subset view also reports several attributes of the transaction set.

When using the GUI for graphs and reports, multiple accounts can be selected at once. Select an account, and then hold the shift- or ctrl-key to select either a range of accounts, or individual accounts, respectively.

Preferences

The preferences object is perhaps the most widely used object in QHacc. It defines how dates are displayed, how currencies are marked, which colors and fonts are used, and which type of bookkeeping you prefer. Any character can be used for a currency symbol, or for the date element separator but I wouldn't recommend using a numerical value for either one (the default of "/" should be good for most dates). The preferences dialog also allows a user to choose the name to display in the titlebar of the program. This is extremely useful when using different personalities, since using different titles for different personalities minimizes confusion.

When switching bookkeeping styles, QHacc performs what I will call "lazy" updating. That is, if you used to use double-entry bookkeeping and you switched to single-entry, none of the links will break. The links between transactions remain intact until the transaction is opened and then resaved. Likewise, single-entry transactions will remain pairless until they are opened as double-entry transactions. This is true even across saves.