# The &keurocalc; Handbook

Éric
Bischoff

    ebischoff@_NOSPAM_nerim.net

2001-2011
Éric Bischoff
&FDLNotice;
2011-01-08
1.1.0

&keurocalc; is an universal pocket currency converter and calculator. This documentation describes &keurocalc; version 1.1.0.

KDE
extragear
KEuroCalc
currency
converter
calculator

## Introduction

&keurocalc; is an universal pocket currency converter and calculator.

On the 1st of January, 2002, 12 European countries united their national currencies into a single one, the euro (€). The same happens from time to time on a smaller scale with new European countries. &keurocalc; helps:

During the transition periods

  - To verify one's bank account, when paying both in euros and in the old currency (Italian liras, for example).

  - To verify one's shopping, and compute the change if paying with a banknote labeled in the old currency.

Many years after the transition periods

  To get an idea of the value of the things in the old currency at any stage of calculations.

At any time

  - To do conversions between the euro and other currencies, like the British Pound, according to the daily exchange rate published by the European Central Bank (ECB).

  - To do conversions between any two currencies that are part of the list published by the ECB.

  - To do conversions between the euro and other currencies, like the British Pound, according to the daily exchange rate published by the Time Genie foreign exchange (TG).

  - To do conversions between any two currencies that are part of the list published by the TG.

&keurocalc; has the following advantages in term of comfort and usability:

- You see every intermediate value and the result in both the reference currency (euro) and in the other currency.

- There is a separate input area where you can type a new value while still having the previous result visible.

- The ergonomy is very close to usual pocket calculators, despite the fact that any value you type can be a value in the reference currency (euro), a value in the other currency, a percentage or an unit-less quantity.

- You press the keys in the order you would speak aloud what you're doing.

- If you make mistakes, a special correction button enables you to correct your last input data, as long as you didn't validate.

- The numbers are displayed according to your locale settings: with either a comma or a dot as a decimal point, according to your &kcontrol; settings.

- You can decide which reference currency you want to use (euro), which other currency to start with when you launch &keurocalc;, and which rounding method to use.

&keurocalc; allows the following operations:

- Conversions from and to the reference currency (euro).

- Systematic rounding of the displayed result, but computations done internally with the precision of the mathematical libraries.

- Usual additions, subtractions, multiplications and divisions.

- Apply a percentage, add a percentage, or subtract a percentage.

- Possibility to store values in an intermediate memory, or use that memory as a running total.

Here are some limitations of &keurocalc;:

- No parenthesized or complex expressions.

- Some roundings go wrong due to the limitations of the mathematical library.

- Inflationist currencies cannot be handled due to limited display size. However, with the change to the new Turkish lira and the removal of six zeroes in that currency, it is not a practical problem anymore.

&keurocalc; never guarantees the exactness of the exchange rates nor the accuracy of the result. You are always invited to verify your computations by some other means. As the license agreement states, there's no liability of the authors if the results are not correct or as expected. Also, please notice that the variable exchange rates are downloaded in an unencrypted and therefore insecure manner from the data sources (European Central Bank and Time Genie). Some man-in-the-middle attacker may confuse &keurocalc; by forging exchange rates. More simply, a transmission error is always possible.

## Using &keurocalc;

### Performing Conversions

#### To convert 1000 Belgian francs into euros

1. Select the BEF - Belgian franc (francs belges) item in the currencies drop down list on the bottom. If that choice is not available, press the Settings... button and select Euro, no network access (fixed rates only) to make the correct rates list appear.

2. Type `1000` on the keyboard or use the corresponding numerical buttons. The digits appear while you are typing them in the Input display. If you make a mistake while typing the digits use the &Backspace; key or the <- button.

3. Press the FB button or the F key. In fact, any key that is not already reserved for some other usage will validate the input as a number expressed in the currency, so B or X would have worked as well.

4. Read the result in the Result display on the right: 24.79 € or 24,79 € according to our locale settings.

#### To convert 25 euros into Belgian francs

1. If the fixed rates currencies are available, select the BEF - Belgian franc item in the currencies drop down list on the bottom. You can skip this step if it's already the selected currency.

2. Type `25`.

3. Press the € button or the E key.

4. Read the result in the Result display on the right: 1008.50 FB or 1008,50 FB. The exact value is 1008.4975, but it's rounded to the closest hundredth of a Belgian franc. The rounding unit depends on the currency and on the rounding method: with the official rounding rules, for Belgian francs it's 0.01 FB, for Italian liras it's 1 L for example.

You could also have typed: `25 Enter E`.

#### To convert 120 German marks into Spanish pesetas

1. If the fixed rates currencies are available, select the DEM - German deutschmark item in the currencies drop down list.

2. Type `120`.

3. Press the DM button or the D or M keys.

4. Just select the ESP - Spanish peseta item to see the same amount of 61.36 € converted into pesetas in the Result area.

### Adding and Subtracting

#### How much is 3 + 5?

1. Type `3` and then press +. Notice that in the result field, `3` is a simple value displayed on just one line, with no monetary unit.

2. Type `5` and then press the Enter button or the &Enter; key. The result `8` appears on the right.

#### You received 100 US dollars and paid 32.50 euros for a book, how much do you have left in your bank account?

1. Make sure that the variable exchange rates are available. If not, press the Settings... to select either Euro, European Central Bank or Euro, Time Genie. Now select the USD - US dollar item in the scroll down list on the bottom. If you have no Internet access, that item won't be available as the latest variable rates between the euro and the dollar cannot be determined.

2. Type `100` and then press $.

3. Press the - button or the - key. Notice the `-` sign in the leftmost part of the Input display.

4. Type `32,50` or `32.50` and then press €.

5. Read the result in the Result display on the right. The exact value might depend on latest exchange rates. Notice that during the whole computation you've been able to read the values both in euro and in US dollars. Pay attention to the fact that different data sources (ECB or TG) might not provide the same conversion rate between the euro and the dollar.

#### You pay a 32.50 € book with a 500 FF banknote. How much was the clerk supposed to give you back, in euro notes and coins?

1. Select the FRF - French francs item in the currencies drop down list if not already selected.

2. Type `32.50` or `32,50` and then press €. You can also type `32.5` without the trailing `0`.

3. Press the - button or the - key.

4. Type `500` and press the FF button or the F key.

5. The result `-43.72 €` is negative, indicating that change money has to be given back to the customer. The +/- button or the S key permit you to change the sign of the result.

Do not try to add euros to simple values (with no currency unit): it won't work, for the same reason you cannot add 5 meters to 3 kilograms.

### Multiplying and Dividing

#### You buy 3.2 kilograms of apples at 2 € per kilogram. How much does the whole cost in Australian dollars?

1. Select the AUD - Australian dollar item if available and if not already selected.

2. Type `2` and press €.

3. Press the X button or the * key. Notice the `X` sign at the left of the Input display.

4. Now type `3.2` followed by the Enter button or the &Enter; key: this means 3.2 units at 2 € each.

5. The result in Australian dollars matches `6.4 €`.

You could also have used the following order: `3.2 = * 2 €` or even `3.2 * 2 €`.

It's not possible to multiply X euros by Y dollars, just as you don't multiply 10 fingers by 2 ears.

### Using Percentages

#### How much is 20% of 3000 yen?

1. Select the JPY - Japanese yen item if available and if not already selected.

2. Type `3000` and press the ¥ button or the Y key.

3. Enter `20` and press the % button or the % key. As with multiplications, the value had to be typed before the percentage.

4. Look at the result: it is equivalent to 600 yen.

#### How much is 3000 yen plus 20%?

1. Select the JPY - Japanese yen item if available and if not already selected.

2. Type `3000` and press the ¥ button or the Y key.

3. Press the + button or the + key.

4. Enter `20` and press the % button or the % key. As with multiplications, the value had to be typed before the percentage.

5. Look at the result: 26.96 € or 3600 ¥ at the time of writing.

#### How much is 3000 yen minus 20%?

1. Select the JPY - Japanese yen item if available and if not already selected.

2. Type `3000` and press the ¥ button or the Y key.

3. Press the - button or - key.

4. Enter `20` and press the % button or the % key. As with multiplications, the value had to be typed before the percentage.

5. Look at the result: 17.97 € or 2400 ¥ at the date of writing these lines.

### Using Intermediate Memory

#### How do I store now and recall later some value?

1. Do your computations.

2. Press Min (Memory in) button to store the value in the Result area. Please notice that the other memory keys now become available.

3. Do some other work with the calculator.

4. Recall the value from the memory by pressing the MR (Memory Recall) button.

Internally, the values are recalled with no unit or in the reference currency (euro) with the maximum precision allowed by the mathematical library. In some rare cases, this might lead to rounding problems if the stored value is a rounded value in a non-reference currency.

#### How do I clear the memory?

1. Press the Reset button. Please notice that the Reset clears everything: the input, the result and the memory.

#### How do I compute 3.1 * 5.2 € + 2.7 * 8.9 €?

1. First compute the first half: `3.1 * 5.2 €`.

2. Store the result in memory with Min button.

3. Now compute the other half: `2.7 * 8.9 €`.

4. Add the result to the memory with M+ button.

5. Recall the sum with MR button.

There are other solutions like `3.1 * 5.2 € Min 2.7 * 8.9 € + MR`.

#### How do I compute 3.1 * 5.2 € - 2.7 * 8.9 €?

1. First compute the first half: `3.1 * 5.2 €`.

2. Store the result in memory with Min button.

3. Now compute the other half: `2.7 * 8.9 €`.

4. Subtract the result from the memory with M- button.

5. Recall the sum with MR button.

The sequence `3.1 * 5.2 € Min 2.7 * 8.9 € - MR` computes the difference in the reverse order.

## Command Reference

### Default Shortcuts

- &Alt; F4
- Exits from &keurocalc;
- &Alt; A
- Displays these help pages
- &Alt; C
- Goes to the currency selection area
- &Alt; H
- Displays the About box
- 0 - 9
- Input digits
- . or ,
- Decimal separator
- +, -, * and /
- Operators: addition, subtraction, multiplication and division
- &Enter; and Return
- Validation of input number considered as a simple, unitless, value
- %
- Validation of input number considered as a percentage
- &Backspace;
- Removal of last input: digits, decimal separator or operator
- &Tab; and &Shift; &Tab; keys
- Moves from one button to the next or previous one
- Arrow keys
- In the currency selection area, moves from one currency to the other
- Space bar
- When focus is on a push button, presses this button
- E or $
- Validation of input number considered as a value expressed in the reference currency (euro)
- S
- Change sign of the result
- Any other key
- Validation of input number considered as a number in the other currency

### The buttons

- 0 to 9
- Input digits
- . or ,
- Decimal separator
- <-
- Removal of last input: digits, decimal separator or operator
- AC
- Clear all: both input and result area
- € or $
- Validation of input number considered as a value expressed in the reference currency (euro)
- The button labeled with the name of an other currency
- Validation of input number considered as a number in the other currency
- Enter
- Validation of input number considered as a simple, unitless, value
- %
- Validation of input number considered as a percentage
- +/-
- Change sign of the result
- Min, MR, M+ and -
- Store result in memory, recall memory into result, add result to memory and subtract result from memory
- /, X, - and +
- Operators: addition, subtraction, multiplication and division
- Reset
- Reset both input, result and memory
- About
- Displays the About box
- Help
- Displays these help pages
- The drop down list with currency codes and names
- Selects an other currency to work with

### The Settings Dialog

#### Reference currency, rates origin

This setting defines from where &keurocalc; should download the exchange rates between the reference currency and other currencies. The following choices are available:

Euro, no network access (fixed rates only)

  Euro is the reference currency. No variable rate is downloaded or used. The only available currencies are the ones that have a fixed conversion rate with the euro.

  This setting is adapted to computers with no network access.

Euro, European Central Bank

  Euro is the reference currency. The fixed exchange rates are available. &keurocalc; attempts to download the variable rates from the European Central Bank (ECB).

Euro, Time Genie

  Euro is the reference currency. The fixed exchange rates are available. &keurocalc; attempts to download the variable rates from the Time Genie (TG).

#### Default currency

This setting defines the other currency that is used when &keurocalc; starts up or when the user validates the new settings.

Notice that the selected currency might not be provided by the selected rates source. In that case, the first available currency in the list is used.

#### Rounding

This setting defines how the results should be presented in the display area. Internally, all computations are done with the precision offered by the mathematical library, but it usually makes no sense presenting tenths of cents. The following rounding methods are available:

Official rounding rules

  The EU conversion rules or other official conversion rules are used. It means that the result is rounded to the next unit for currencies like the Japanese yen or the Italian lira, and rounded to the next hundredth of unit (cents) for currencies like the euro or the dollar.

  For example, 158.323 yen would be rounded to 158 yen. 12.537 euro would be rounded to 12.54 euro.

Smallest coin method

  The result is rounded to the next value of the smallest coin that circulates in the country that uses that currency. For disappeared currencies like the Italian lira, it uses the smallest coin that used to circulate before the currency has been withdrawn: in the case of the Italian lira, it was the 50 liras coin.

  For example, 1235.9 Italian liras would be rounded to 1250 liras. 39.45 Norwegian crowns would be rounded to 39.50 crowns.

  We lack information about the smallest coins that exist in every country. Please send a bug report if &keurocalc; uses an incorrect value for the smallest available coin in your country, and we will enter that information.

No rounding at all

  The computed value is displayed unchanged, as a floating point number.

#### Look and feel

This setting defines the appearance and behavior of &keurocalc;. The following options are available:

Display color

  The background color of the display areas (both input and result). To change the background color, click on Change.... This opens the standard &kde; color selection dialog. Choose a new color, then press OK to validate the new choice.

Enable splash screen

  Uncheck this box if you do not want to initial picture to appear when &keurocalc; starts.

## Credits and License

&keurocalc;

Program copyright 2001-2011 the &keurocalc; developers:

- Éric Bischoff ebischoff@_NOSPAM_nerim.net - design and implementation

- Gil Gross ptit.ours@_NOSPAM_gmail.com - additional functionality

- Melchior Franz a8603365@_NOSPAM_unet.univie.ac.at - design and testing

- Bas Willems cybersurfer@_NOSPAM_euronet.nl - graphical artwork

Documentation copyright 2001-2011 Éric Bischoff ebischoff@_NOSPAM_nerim.net.

Documentation reviewed by &Philip.Rodrigues; &Philip.Rodrigues.mail;.

&underFDL; &underGPL;

## Installation

### How to obtain &keurocalc;

&keurocalc; is part of the KDE extragear-utils package. The latest version of &keurocalc; can be downloaded from its home page.

### Requirements

In order to successfully use &keurocalc;, you need &kde; 4.0.

All required libraries can be found on ftp.kde.org, the &FTP; site of the &kde; project.

### Compilation and Installation

In order to compile and install &keurocalc; on your system, type the following in the base directory of the &keurocalc; distribution:

    % mkdir build
    % cd build
    % cmake ..
    % make
    % make install

Since cmake autodetects your system settings, you should have no trouble compiling &keurocalc;. Should you run into problems please report them to &keurocalc;'s authors.

&documentation.index;