FAMe 1.6 User's manual
Back to index
Installation
Nothing special to do with the KISSlib, which should still remain local (in the FAMe/lib/ folder)
because the API is not frozen yet.
On the other hand, you should install the MIME types if you' re a first time user; most tiny bits
are installed automatically by the OS, and FAMe will offer to do the rest for you when
launched ("the rest" is the accountfiles' fancy icon).
Uninstallation
First delete the FAMe MIME types with Menu-Misc/Uninstall MIME types then
quit FAMe and delete it as well as its settings folder (~/config/settings/FAMe/).
Overview : getting started
Don't forget that by moving the mouse cursor over (most of) the buttons
you can have a short description displayed in the status bar, at the bottom of the account window.
Besides, the text is context-sensitive, for example when
a button is disabled it tries to explain why.
Main window's layout
The upper part of the window
(accounts box) changes according to the currently selected account, displays its
real balance and its balance confirmed by bank statements.
When you first launch FAMe, there are no hard-coded accounts nor any other field. Adding some
built-in non-account fields is an option but you're not forced to do so, and it seems people
generaly prefer to customize them. First open the Accounts list via the menu and add at least one
account (click on the "Add" button and change the default name).
Regarding the Means and Categories, both adding of predefined ones and adding of custom entries
is accessible in the matching window's menu items. (see
the paragraph about the list-requester).
An account is made of the transactions it contains. They are displayed in the
transactions box just below. Add or delete transactions with the corresponding buttons.
A transaction is composed of fields (fields box),
such as its amount, who the recipient is ..etc (see below).
You may load / save your accounts file
in, you guessed it, the file menu.
Using it should be very infrequent in typical one user situations (you're prompted to save
the file when exiting).
A special item of this menu is "Export as ASCII" : if you want to print all the transactions
of the current file or to have a "backup" in plain text format, this is the way to go.
Main window's Fields-box
From left to right you have : the date
when the transaction occured, its amount (with a minus sign if the account was debited),
the destination account if it was internal to the file (or the person if it was external), what
type it is (taxes, entertainment, salary...etc) and what mean was used for the transaction
(check, credit card ...etc).
The Description text-control at the bottom will be used typically for a check-number,
but it may hold any additional information you want, within the 255 characters limit.
No fields items are predefined except the "none" item,
customize them in the "Fields" menu. (see below).
The "confirmed" check box's use is to remember if a given transaction has been
reported on a bank statement or not yet.
Note that an "internal" transactions (that is, transactions whose source and destination
are both one of the accounts of the current file) have two distinct "Confirmed" flags : when
receiving your bank statement you may "tick" a transaction confirmed in the first account
after reviewing it, then mark it confirmed separately when you check the second account.
Internal transactions are drawn in violet, by contrast to classic (black) External transactions.
To enter a "debt" value as an amount, you have
to add a 'minus' sign in the string gadget :
50 will be a credit and
-50 will be in the left column (debited)
Note that the "add-window" uses the same layout and always adds
transactions to the currently selected acount.
The four Popup-menus embody the list-Fields :
About list-Fields
- Accounts : list of one or several accounts, possibly in distinct banks, but they should
all belong to the same person : a good policy if several people use FAMe is to have one
.fame file per person, containing all her/his accounts.
- People : list of the "third parties" to/from whom the transactions go ; for example
your fave supermarket (expenses), your boss (income), your relatives
(possibly both income and expenses) ...etc
- Means : check, credit card, transfers ...etc. Add whatever payment means you use.
- Types : taxes, entertainment, salary, misc. income, misc. expenses ...etc
All field lists include an item named "none" that you can use for exceptional cases transactions
when adding a special item isn't worth it. The "comment" text-control may then be used to
give more details. The exception is the Accounts field whose "none" item cannot be used.
The Field Window (or "ListField Requester")
Invoked in the second menu (the same interface for all four fields). Its purpose is to add or delete field items
(Add and Del buttons) and rearrange their order. (Up and Down
buttons respectively). The "none" item is not editable and never appears in the list.
The last menu item allows you to add built-in entries, like "Food", "Credit Card" ..etc so that
you don't have to type them if you're a first time user. You don't have to accept all of them :
all the newly inserted entries will be selected after the operation, you're then
able to unselect the ones you wish to keep , leave the others
selected and hit the Delete button.
Multi selection follows the standard BeOS guidelines, here's a clip from the BeBook :
The user can select any number of items by holding down an Option key (for
discontinuous selections) or a Shift key (for contiguous selections).
The only action that can be performed when several items are selected is Delete.
When Deleting multiple items, you're limited to none as a replacement item, this
will be corrected in a future release.
Add will perform insertion right above the selected item if any, or at the end of
the list if no items are selected.
Disk operations
QIF export
Be aware that QIF files hold individual account data only, so exporting to a QIF
file will only write the currently selected account's data.
QIF Import : overview and supported tags
To import a Quicken Interchange Format (QIF) file, just open it normally.
Transactions will be inserted in the currently selected
account (thus, you must have created an account before importing). Both *nix and
MS-style carriage returns are supported.
The QIF Import features is still somewhat *experimental*. I've heard at least one success
story and tried it myself with some MS-Money generated QIF export files someone was kind
enough to provide me with; if something is
wrong let me know.
[if run from a Terminal, FAMe might output some info that would be valuable
for me to understand what is going on].
The header this import feature was most tested with it "!Type:Bank" but all
non-investment types ( !Type:Bank, !Type:Cash, !Type:CCard, !Type:Oth A and !Type:Oth L)
are supposed to be recognized.
Only the meaningful (in FAMe parlance) QIF tags are implemented, for example
"investment" has no sense for FAMe and will generate a warning if encountered :
Tag | Supported ? |
A (Address) | No (but might be added to description in a later implementation) |
C (Cleared status) | Yes |
D (date) | Yes |
E (Split memo) | No (irrelevant ?) |
M (Memo) | Yes |
N (Check number) | Sort of (appended to the transaction description) |
T (amount) | Yes |
S (Split category) | No (irrelevant ?) |
$ (Split) | No (irrelevant ?) |
others | No (no equivalent in FAMe features ..etc) |
Here's a sample QIF file to give an idea of the
supported format.
Charts
The Charts window is mostly intuitive and allows to generate Diagrams (Pie-charts
or Bar-charts) based on settings one could call 'Queries' ala SQL. You may quickly select
predefined queries in the main PopUp menu or switch to manual/custom
mode and benefit from the powerful definitions system. Beware, time flies when playing with this....
"Stat transactions..."
This is similar to the SELECT statement of SQL, i.e. this allows you to select a subset
of all the transactions contained in the file to be a part of the computation, or all of them, or
any where in between (based on various criterions); the choice is yours.
"Totalize..."
Select here what the vertical axis should be labeleld with, either the sum of transactions' amounts,
or just the number of transactions involved.
"Sum up per..."
Put simply, this is where you choose what to display on the horizontal axis. Another way to say it :
select the discriminant field. e.g., select Date and the generated diagram's data
will be sliced based on each transaction's date.
"Show as..."
The above settings defined how to add up some amounts into an array, this box lets
you choose the type of diagram to embody it : a plain bar chart of each element of
the array, of relative percentage of each element of the array versus the total amount (pie-chart).
This total amount appears at the top of the diagram, by the way. When you have
a "full selection" in the first box, this also happens to be the total balance of your accounts.
(and now you have one less "tip" to read).
"Restrict to..."
You can think of this as a mix from the WHERE and FROM statement from the SQL language.
The three listviews should be self-explanatory. Tip : although checking the
e.g. "restrict to accounts" checkbox and highliting all of its contents yields the same results
as unchecking it, the latter yields results more efficiently (i.e., faster !).
On the right part apears of course the diagram corresponding to your query, and below that
all the element it's made up are in a listview, whose items you can select to highlight it in the diagram.
Please note :
- Month [linear] : not implemented, would stat all month individually
- Month [cyclic] : if stating 2 years, january will account for first PLUS second year ..etc
These "queries" are specific to a given document/file because of the "restrict to.." fields,
which is detailed in the following two "insight" paragraphs:
Consistency vs Fields
A real Observer pattern isn't yet applied on the "restrict to.. " listviews, therefore
consistency vs deleted field entries (the only existing inconsistency issue) is applied
only when the window is (re)opened, as the listviews aren't able to select items
that no longer exist. I'll look into implementing immediate-consistency enforcement even
when the chart window isn't opened in the future.
Scope
Because of the "restrict to.." field item dependancy
the chart views are tied to a particular accounting
document (each query with 1 or more checkbox checked references field items in the document)
and thus are saved in the account file rather than as an app
setting, which would be trickier to keep consistent.
Automatic (aka Regular) transactions
Once you get up and running you'll probably quickly notice that some
transactions are recurrent (e.g. phone bill unfortunately coming back
every month, or food expenses every week and so on).
To save some typing (and potential errors) FAMe provides you with a flexible
auto-trans mechanism, ie lets you configure a set of transactions to be submitted for
addition on a regular basis.
You may setup as many auto trans as you want in the auto trans config window
(Menu Transactions->Automation) and FAMe, upon startup,
will scan the list whenever the accounting file is loaded, to see if there are some to
apply since the last time it started, and apply them interactively (ie each transaction
is shown to you and you can alter it before it's added, or even ignore it ..etc).
Reg trans config window
One subtility: the date _below_ is important.
It determines the day for "every month" frequency.
So there's no "apply every month on the 1st"
but instead "apply every month, period" because
the "on.." part is just the day you mention in
the date !
And, as to determining the hour for an
"every day" frequency it didn't seem useful enough
to implement a special case here.
The date you set represent the next time you
want it to happen and will be automatically
increased by the period you set whenever FAMe scans
the auto trans list.
So if you set it to be somewhere in the past, there are
some transactions pending already, that will be applied
the next time you reload the account. Can be useful at times..
Regtrans effective adding window:
Whenever you run FAMe it will scan the auto-trans
you have set up in the AutoTrans config window
and will ask you if you want to actually add
all transactions whose applying date has been reached.
- Add & Next : click this to add that transaction and proceed to
the next pending auto-trans, if any.
- Ignore & Next: do not add, though it registers
as if it had been, so that it won't ask you again. Thus it's lost
forever, and if you change your mind you'll have to enter
the transaction by hand.
- If you get bored, choose Stop and it will suspend
the cycle; the remaining ones to add are not lost,
they will be asked the next time you run FAMe again.
Note that changes that you apply in this window only affect
the transaction that will be added and not the one you've
configured in the "automatic trans window", thus one can
say the latter one really serves as a templates container,
and you're free to modify the transaction when it gets
pending, depending on the specifics of that particular instance.
Consistency vs Fields
Field item renamings are totally transparent just like in
the rest of the app.
If a field item is deleted though, the behaviour of
the auto trans config window is to set the popup to (none)
(the reply you give to the "replace with what" requester
only applies to the account body itself at the moment, unfortunately..)
Scope
Auto trans are strongly dependant on a particular accounting document,
and thus are saved in the account file rather than as an app setting.
Preferences
They're stored in /boot/home/config/FAMe/ .
Just like the main 'accounts data' file, the preferences will stand the test of time because of
the expandable format allowing for improvements without breaking compatibility.
Incidentally, this goal was achieved in different ways : the accounts
file is in IFF format while the preferences are all flattened BMessages.
- Storage / incremental backup
-
No backup : if you choose this the working file is the one to which the next "Save"
will be performed, plain and simple. (without even an intermediary file in case the power
goes out while the file is being overwritten).
-
Limited backup : in this mode,
the previous version of the working file is renamed before saving some new content,
and if it cannot be saved under a generic "bak" name because this is already taken,
FAMe will recursively rename accout files until the name is free or it reaches the limit
and thus flushes the oldest file. The limit can be modified in the text control below and specifies
the upper limit of the quantity of backup copies being kept. Also, the names will have
something special in their name (a "date" like 6 digits number) to avoid this operation
to become increasingly slow with time.
- Storage / Open Previous
-
The text entry widget is for you to specify how many files the "Open Previous..." menu
should remember. Entering a value of zero deactivates maintenance and thus reduces
the size of /boot/home/config/settings/FAMe/lastfiles.msg to the minimum.
This file is loaded at startup and saved when you quit. Entering a value of 'n' will remember
the 'n' distinct files opened and they will be displayed from most recent at the top to oldest
at the bottom of the menu.
- Rest of settings:
-
They should be self-explanatory. If not, contact me and i'll gladly add
an entry in this manual.
Localization
The localization process changed since the 1.4- versions. Contact me directly for more info.
Hints and Tips
I might implement a "Tip of the day" at some point in time ; for the time being here are a few
worth mentionning :
- Keep your FAMe settings in a safe place
- Unlike some applications (including some shipped with BeOS -- Ugh!) FAMe is
totally symlink-friendly, i.e. you may move the ~/config/settings/FAMe/
folder onto another partition (and create a symbolic link to the new location)
so that you don't have to backup it whenever
you initialize your /boot volume to install a BeOS upgrade.
- The global situation at your fingertips
- The overall balance of all accounts (and other useful stuff) in mentionned
in the charts window : select the "Income vs Expenses" predefined
setting (for example, but the overall balance of course doesn't change when switching
to some other settings) : your total fortune is mentionnned at the top of the window :-).
Generally speaking, be aware that the Charts window assumes the same
currency is used in every account : it adds up the amounts without performing
currency conversions.
- Charts and initial amount
- You probably set the starting balance of your accounts with an initial transaction.
In order for this not to show in the charts, just set the "from Date" widget to ignore
this, for example set it to the day next to the initial deposit.
- Auto loading a file
- Make a symlink (symbolic link) to an account file instead of a link to the
FAMe executable, for example on your Desktop.
- Keyboard navigation
- In the "Add new transaction" box you can jump between the description field
and the amount field with Alt-Tab (or Shift-Alt-Tab depending on your current location).
Error requesters and how to handle them
- "Recoverable Error"
Requester box whose aim is to inform the user of an internal error which doesn't
affect the stability or Document integrity.
Even though it isn't easy to differentiate from a "normal" error yet, this is not a plain error-handling requester but more like the report of an internal design flaw,
(failed asserts)
thus the mere fact that you see one is important to me so you should copy the short error message somewhere and email it to me.
Recoverable Internal Errors are not localized because, er, they ought not
to happen anyway.
- "Unrecoverable error"
None implemented to date.
Known bugs and ToDo
- The account deletion is not implemented yet.
- Refer to my homepage for more up-to-date infos on bugs and issues.
The icons used herein are the property of Be, Incorporated and are used by permission.
(necessarily so as they're loaded locally :-)