Configuration file format
Since UnitConv now includes an internal editor that can be used to customise the conversions, it is strongly recommended that the editor is used for all customisation. If it is necessary to edit the configuration file manually in a text editor, the following information on file format is included. The overriding maxim is to always make a copy before modifying the file. Then if something bad happens, the original working version is still available.
To allow the conversions to be customised to each users preference, the data is now held in a text file, which is read by the application when it initialises. The file may therefore be modified in any text editor. The format of the file must be carefully adhered to, otherwise errors will be generated. If an error occurs, then the application will use a default set of conversions. A full description of the file format is given below.
To edit the file, double click on !UnitConv while holding down the SHIFT key. This will open the application directory. Within this directory, there is a text file named unitsdata. Make a backup copy of this file before attempting to make any changes. Load unitsdata in to your text editor, either by dragging to the editor iconbar icon, or by double clicking SELECT on the file icon. After making your changes, simply save the text file back. The next time !UnitConc is run, the new data will be used.
File format
Examining the units data file in a text editor should show the format to be, I hope, simple and obvious. In the following table, the file entries are shown on the left, while an explanation is given on the right.
#UnitConv:version 1 | This must be the first line, and is used to confirm it is the correct file, and to identify the version of the file format (in case it changes in some later incarnation of the application). |
#this is a comment | Any line starting with the hash (#) symbol, other than the first line, will be treated as a comment and will be ignored. Blank lines will also be ignored, so this helps the readability of the file. |
total_groups:2 | The integer (in this case 2) identifies the number of different conversion groups that will appear in the menu available from the menu button at the bottom right of the main conversion window. Note that there will always be an additional menu item (special) available as well. These special conversions are hardcoded into the application, because they involve conversion algorithms more complex than simple multiplication and division by a constant factor. |
group_title:Common | This is the first menu item, and the text to the right of the colon will appear in the menu exactly as in the file. |
group_entries:8 | The number of radio icons that will be displayed in the right half of the conversion window whenever that particular menu item is selected. Version 2.00 of UnitConv allows a maximum of 9 icons. |
group_item: | This identifies the start of a set of conversions. |
Length,5 | We now have the data for a set of conversions. The first line contains the text that will be displayed against the radio icon in the top right of the main window, followed by the number of different units in the group. A corresponding number of fields will be displayed in the left half of the main window. The data pairs must always be comma separated. Version 2.20 of UnitConv allows a maximum of 9 fields. |
cm,100 metre,1 in,39.3700787 ft,3.28083989 mile,6.21371192E-4 | The actual units, together with the factors required to interconvert. I think the easiest way of doing this is to select one of the units as the "base", giving it a factor of 1, and then each of the other units will have a factor corresponding to the number of those units in 1 base unit. For example, there are 100 cm in 1 m, 39.3700787 inches in 1 m, 3.28083989 ft in 1 m, and so on. All arithmetic uses double precision, although the result of the conversion is rounded to 5 figures. Large or small conversion factors can be entered in scientific format. The number of data pairs here must correspond to the number already declared in the first line of the group_item data. |
group_item: Time,4 seconds,86400 minutes,1440 hours,24 days,1 | There then follows further groups of data, in the same format as described above. The number of these groups must correspond to the number declared in group_entries. |
If the total number of groups initially declared (total_groups) is greater than 1, then the whole data structure repeats (from group_title), for however many groups in total there are. |