JCT 1.0 - QUICK USER GUIDE                                        July 10th 2004
==========================

   Note : this document was written to address comments from users requesting an English
   manual. We do not have time enough for now to translate the whole French manual right
   now, but we do hope this quick guide will help you discovering JCT.

1. General Informations
=======================
   
1.1 Aim
-------

   JCT lets you draw thematic maps, ie paint countries according to numerical values.
   
   JCT was written by two Swiss students as their semester projet at EIVD
   [http://www.eivd.ch/]. The software was ordered by DFJ [http://www.dfj.vd.ch/]. It is
   intended to be used in colleges by teachers and students.
   
   Of course you can use JCT for many others purposes. However, its features are quite
   simple and won't fullfill the professionnal user needs. Still, JCT is an interesting
   tool to make quick thematic maps.

1.2 Data sets
-------------

   JCT uses data sets, they are folders that contain a file whose name ends with .jct
   extension and a data folder. Two data sets are given with JCT in the 'cartes' folder
   ('cartes' means 'maps' in French). For now JCT ships with Europe and the World. Other
   data sets will be made avaliable on JCT web site in the future.
   
   JCT was designed to let teachers and students easily modifiy the data, using the
   included editor. However, you can't modify the maps yourself, neither you can import
   maps of your own. Data sets building is a complex task, described in JCT technical
   documentation. Do not modify the files in the data folder unless you know what you're
   doing.
   
   If you create interesting data sets and you think they might be useful to other
   schools and students, do not hesitate to submit it to JCT, we will put it on the web
   site.

1.3 Configuration required
--------------------------

   JCT runs on Apple Mac OS X, Microsoft Windows and Linux. It requires Sun Java Virtual
   Machine version 1.4.x.

1.4 Availability
----------------

   JCT is published on http://jct.sf.net/

1.5 Licence
-----------

   You can download and modify JCT freely, it is free software, under GNU GPL licence.

2. Install and uninstall
========================

2.1 On Mac OS X
---------------

   Just download JCT from the web site. That's all, a 'jct' folder was created on the
   desktop. JCT is installed! You can use it directly or move the folder to the place
   you want.
   
   If you got JCT from another place, you may have to open the file jct.dmg and copy its
   content to the place you want.
   
   We advise you to put the JCT application in the computer's Applications folder and
   the 'cartes' folder in the user's Documents folder.
   
   To uninstall JCT and its associated files from you computer, juste delete JCT
   application and the 'cartes' folder, which should be in the user's Documents folder.

3.2 On Windows
--------------

3.3 On Linux
------------

3. Running JCT
==============

3.1 On Mac OS X
---------------

   You can run JCT by double-clicking on its icon, or by opening un .jct file.

3.2 On Windows
--------------

3.3 On Linux
------------

4. Controls
===========

4.1 At opening
--------------

The windows is empty. All you can do is use the menus or close the window.

4.2 After data set opening
--------------------------
   
   You can open a map with File > Open... In Mac OS X you can also double-click on a
   .jct file. The main window and the menus are then refreshed.
   
   About export, please note than gif format suits better JCT maps; the files are
   lighter and better quality.
   
   The main window contains several elements. From left to right and top to bottom we
   have :
      - navigation tools
        Use them to move on the map and change the scale. On Mac OS X you can also
        click on the map with ctrl to zoom in and shift-ctrl to zoom out. If you're lost,
        click in the center of the arrows, the map will be recentered
      - data selection tools
        Use the Main value menu to choose a data you want to display. The second menu,
        Divisor, let you eventually divide the fist one.
        For example, if you want to display the population density, you can choose
        population in the first menu and surface in the second one.
      - legend field
        Here you can add a box that contains the title of the thematic map and the
        values matching the colors. The 'Data in percents' checkbox, when checked, changes
        the numerical values display in percents.
      - the paintbrush
        Opens the 'Ranges' window (see below)
      - the main display area
        It is where the map is displayed. You can move by clicking on the sport you
        want to center. You can also click and drag the mouse to select an area to magnify.
      - the status bar
        At the bottom of the screen, the status bar is useful to display the name and
        value of the area the cursor is on.
   
   The 'Ranges' window opens when you click on the paintbrush icon.
      - data layout
        You can 'cut' your data in two ways : by equal ranges (the sets will have the
        same range) or equal cardinalities (each set holds the same number of countries).
        
        Example : consider the set [1,2,3,10]. Spliting this set into two groups of
        equal ranges will result in [1,2] and [3,10]; each group is made with the same number
        of values. By Equal cardinalities, the groups will be [1,2,3] and [10]; each group
        has the same range, here from 1 to 5 and from 6 to 10.
      - number of colors
        A small menu lets you choose the number of colors, ie the number of data
        groups. You can choose up to 8 data groups.
      - the colors
        Colored squares let you choose the color you want to give to each data group.
        Click on them to change the color. Note the 'no data' square, it sets the color to
        use for countries for which we have no data.
      - the 'Auto shading' checkbox
        When checked, data groups are given colors according to a shading between the
        first and the last group.
      - the 'Refresh' button
        Updates the map.

4.3 In the Data Viewer
----------------------

   You can open the data Viewer from the menu: Data > Display...
   
   There you can see the raw data used to draw the map. The columns are the fileds in
   the toolbar 'main' and 'divisor' menus. The rows match with the countries. Note that
   the two first columns are for internal usage and cannot be modified.
   
   This window has a menu on top. From this menu you can enable editing. You will be
   asked for a password. By default, the password is 'jct'. You can change it in the
   same menu.
   
   When you're allowed to modify the data, tree buttons appear at the bottom of the
   window : add a column, delete a column and save.
   
   You can use the data viewer as a minimal spreadsheet: click in a cell to edit its
   content. Note that you can't use commas (','). If you enter one, it is changed into a
   dot ('.').
   
   Values that are not legal numbers will go into the 'no data' group.
   
   You can also change the columns labels by double-clicking on them. This label is used
   in the selection menus of the main window. Here again, commas are not allowed.

4.4 While reading informations
------------------------------

   The 'Data Info' window can be opened from the menus > Informations...
   
   It gives some informations about the statistical data such as the source, the date
   and so on. You can use this window to add comments of your own.
   
   As in the Data viewer, the file is editable if you can enter the right password.

4.5 Passwords
-------------

   There can be a password per data set. The maps given with JCT all have a default
   password which is 'jct'. If you want to use JCT with pupils, consider changing this
   password. Note that the aim of the password is not so much to remain secret but
   rather to avoid deleting data by error.
   
   If you forget the password, there is a password that is always accepted; please see
   the annexe documentation.

5. Step by step guide, use example
==================================

6. What JCT do not do
=====================

   JCT can't do some things such as :
      - draw or import your own maps
      - print directly from jct

7. Known bugs
=============

   Under Mac OS X, menus are not always refreshed.

8. Error dialogs
================