jMileage - Calculate the gasoline efficiency of your car.

Table of Contents:


This software is released under the terms of the GNU Public License. Please 
see the file COPYING for more information.


Freeware

This software is freeware. Please feel free to use it as you see fit. If you 
make changes, be aware that it is released under the GNU Public License. If 
you truly enjoy using this software and wish to compensate the author, 
donations are accepted. You can donate via PayPal or any other 
person-to-person donation service. Just send however much you feel is 
appropriate to jasonshah@yahoo.com. Thanks in advance to anyone who feels 
like contributing :)



Overview

This application lets you track the fuel efficiency of your automobile. Simply 
enter the mileage and amount refilled on each visit to the gas station, and the 
application takes care of the rest. It provides a history of intervals with 
the gas mileage between those intervals, as well as the average gas mileage of 
all recorded entries. Using this application as intended may even indicate 
problems with your automobiles, as significant changes in fuel efficiency may 
be a symptom of certain problems.



Installation

Just double-click on the jMileage.prc file to alert the HotSync manager that 
you want to load it on the next sync. Note that this is only for Windows 
users. Mac and Linux users, consult your appropriate manuals.



Usage

1. When reaching a gas station for the first time, enter the mileage into the 
'Mileage start' field. Choose 'Save'.

2. On subsequent visits to the gas station, after filling up enter the mileage 
into the 'Mileage End' field and the amount refilled into the 'Refill amount' 
field and choose 'Save'. A record of this visit is then stored.

3. To change which automobile you want to record gasoline efficiency for, 
simply choose the automobile you are entering/viewing data for, as you would a 
PalmOS category (such as in Datebook/Address/MemoPad). You can edit the 
categories via this menu as well.

4. To edit an entry, select it and choose Edit Entry from the Main menu. 
Make your changes and choose OK.

5. To delete an entry, select it and choose Delete Entry from the Main menu. 
The entry is then deleted.

6. To see more details about a specific entry, simply tap the area below the 
list of older entries. This will bring up a dialog of statistical information 
for this entry and for all entries. The dialog contains the following 
information:
- Total cost of this fill-up
- Cost per unit distance (e.g. cents per mile) of this fill-up
- Average cost per unit distance (e.g. cents per mile) of all fill-ups.
- Cost per day (e.g. cents per day)
If you have any other suggestions as to what should go here, let me know.

7. To export your data to a memopad file, choose Data/Export to Memo. This 
will create a memo containing your data in CSV (comma-separated variable) 
format, importable to your favorite spreadsheet.


ZIP File contents

The following hierarchy shows the contents of this ZIP file:
Root
|- README, COPYING: two files you should read
|- jMileage.prc: loadable file
|- source
|- *.*: sources from v1.5 of jMileage
If you wish to see earlier versions, email me and I will send them.


Version history

1.0: 
- Initial release. Very simple :) Just three fields and two buttons on a form.

1.1:
- User interface overhaul
- History list showing date entered, start, and end mileage
- Menu support
- Preference storage/retrieval
- Database storage/retrieval

1.2:
- User interface and database update to support 3 cars
- Deletion of list items

1.3:
- Preferences screen
- Label changeable: from MPG to KPL or Km/L (similar for Avg MPG)
- Date format changeable: 12/31/01 to 31/12/01, 21.12.01, or 31-12-01
- Upgrade integration more advanced
- Small bugs fixed

1.4
- Edit screen
- Update to labels: KPL becomes L/100Km, and selection of this label changes 
output (i.e. M/G --> G/M*100)
- New or updated entry moved to correct place on insert/edit
- More UI enhancements and more bug fixes

1.5
- More details screen
- Significant UI changes
- Entry of cost/unit quantity and notes allowed
- Greater precision on refill quantity field
- Delete confirmation
- Hard up/down keys scroll through main form list

1.6
- Export to Memo menu item added to facilitate simple exporting of all data
- Cost/unit distance and Avg cost/unit distance updated to a more 
understandable format


To-do

- More organized and informative Details screen (let me know if you have ideas!)
- Scrollable MPG (and other metrics) chart (let me know if you have ideas!)
- User-customizable category assignment and filtering (i.e. assign which gas 
station the fuel came from, then filter based on gas station)
- Extrapolation based on distance (MPG from X miles away), date (MPG from Y 
date), and fill-ups (MPG from Z fill-ups previous)

Any others suggestions? Let me know!



Open-source

This program is open source, released under the GNU Public License. See 
COPYING for more information on this. As a learning aid, the following topics 
are dealt with in this program:
- Floating point numbers (ack!). This is a very ugly subject with the PalmOS, 
and while I am sure that my method is not the greatest, it is functional.
- Saving and loading preferences between iterations of the program.
- Database record storage, retrieval, and modification
- A very hybrid form of categories
- Menus 
- Thoughtful user interface
- Exporting to memopad
- Standard topics, such as forms, controls, drawing to a window, etc.


Email questions or comments:
jasonshah@yahoo.com

Thank you
Jason Shah