*Mental calculation* a simple tool made, to practice *anzan* - mental calculation made by visualizing a soroban, the japanese abacus.

http://en.wikipedia.org/wiki/Soroban

Requirements:
=============

for the Windows version:
------------------------
All dependancies are included.
- espeak for the speech synthesis (as an option)

for the source version:
-----------------------
- python 2.6 (or higher)
- PyQt4 4.7 (or higher)
- qt 4.6 (or higher)
- phonon (Watch out: there is a bug in phonon 4.6.0 that completly breaks this software. Try to use the 4.5.1 version)
- espeak for the speech synthesis (as an option)

Downloads:
----------

Python
  http://www.python.org/download
Qt
  http://qt.nokia.com/downloads/downloads#qt-lib
PyQt
  http://www.riverbankcomputing.co.uk/software/pyqt/download
eSpeak
  http://espeak.sourceforge.net/download.html

Espeak
======

*mentalcalculation* will look for *espeak* executable at its default location:
    - C:\Program Files\eSpeak\command_line\espeak.exe for Windows
    - /usr/bin/espeak for Linux

If it is found, you will be able to use the speech synthesis option to get the number spoken out automatically.

If, for any reason, *espeak* is installed in an unusual location, you must specify its path in the configuration file. See below on how to do that.

*Espeak* will automatically use the language defined by your locale.
If you want to change the language used by espeak, change the lang variable in the [Espeak] section of the config. file.

Configuration file
------------------
*mentalcalculation* saves its settings in a configuration file: 
On Linux/or any unix-like
  ~/.config/mentalcalculation/mentalcalculation.ini
On Windows
  C:\Documents and Settings\<your_user_name>\Application Data\mentalcalculation\mentalcalculation.ini for Windows XP
  or
  C:\Users\<your_user_name>\AppData\Roaming\mentalcalculation\mentalcalculation.ini for Windows Vista and above

You might need to change the options of the Windows explorer to be able to see hidden files and directories
to be able to access the configuration file.

You need to run *mentalcalculation* (and close it), at least once so that the configuration file is written to disk.

Note: It does not do anything to the Windows registry at all !

Customization
=============
The default configuration file looks like this:

    ; comments are lost after mentalcalculation starts
    [General]
    digits=1
    rows=5
    timeout=1500
    flash=500
    hands_free=false
    neg=false
    no_plus_sign=false

    [GUI]
    fullscreen=false
    font_color=#000000
    background_color=transparent

    [Espeak]
    cmd=C:\\Program Files\\eSpeak\\command_line\\espeak.exe
    lang=en
    speed=170 ; words per minute from 80 to 390

    [Sound]
    one_digit=false
    speech=false
    annoying_sound=false

Colors
++++++
You can change font and background colors in the [GUI] section. Change font_color and/or background_color to valid HTML color codes or use explicit name. For more details, look at http://doc.qt.nokia.com/latest/qcolor.html#setNamedColor
If you look for a way to choose a color, you could use the color picker of your favorite graphic software, or go online at http://www.colorpicker.com/, or http://html-color-codes.info/. A search for "color picker" or "visual color picker" on your search engine gives you plenty of solutions too.

Fonts
+++++
One can use a custom font for the display of number. Add a font variable in the [GUI] section. The variable should only hold a family font name. For example:

    font=Times New Roman

Sound
+++++
Change annoying_sound variable in the [Sound] section to true to get a sound every time a number is displayed on screen.

The sound is played only if you don't use the speak synthesis system.

By default, the file called annoying-sound.mp3 in the sound directory of *mentalcalculation* is used. You can change it to any sound you like.

Plus sign
+++++++++
One can remove the + sign in front of numbers if using subtraction by using this snippet in conf. file

    noplussign=true

in the [General] section of the mentalcalculation.ini

Tracking Usage
++++++++++++++
With the 0.3.5 release, every time you launch *mentalcalculation*, it tries to reach www.sorobanexam.org/mentalcalculation?ping=UUID. The UUID is a randomly generated uuid v4. No information is sent. It just allows us to gather statistics about the usage of this software and know if people only download it once and never use it again, or if it is really used often.

You might not like that tracking behavior, so you can opt-out. In mentalcalculation.ini, you can add a line:

    uuid=opt-out

in the [General] section; you can also use any of the following values: no, No, none, None, false, False, optout or leave it empty.

Or if the line is already there, just change the value of uuid to one of the string mentionned above to opt-out.

That tracking behavior will normally be removed on the next release.

Fail-safe mechanism:
--------------------
There is a fail-safe mechanism that allows *mental calculation* to safely fail when it does not find one of its resources files. So, if you don't like the smileys/emoticons or the sounds, you can safely delete/rename them on your harddisk (img/sound directories), and *mentalcalculation* will continue to work without them.

Attribution:
============
I would like to thank the Tango project from which I borrowed some icons and the GNOME project (gnome-media, gnome-audio) for the sound files I use.

Soroban image courtesy of burlie (@Flickr) see http://www.flickr.com/photos/burls/

vim: set ft=rst: