1% BEGIN LICENSE BLOCK
2% Version: CMPL 1.1
3%
4% The contents of this file are subject to the Cisco-style Mozilla Public
5% License Version 1.1 (the "License"); you may not use this file except
6% in compliance with the License.  You may obtain a copy of the License
7% at www.eclipse-clp.org/license.
8% 
9% Software distributed under the License is distributed on an "AS IS"
10% basis, WITHOUT WARRANTY OF ANY KIND, either express or implied.  See
11% the License for the specific language governing rights and limitations
12% under the License. 
13% 
14% The Original Code is  The ECLiPSe Constraint Logic Programming System. 
15% The Initial Developer of the Original Code is  Cisco Systems, Inc. 
16% Portions created by the Initial Developer are
17% Copyright (C) 2006 Cisco Systems, Inc.  All Rights Reserved.
18% 
19% Contributor(s): 
20% 
21% END LICENSE BLOCK
22
23The map* files gives an example of using both the Tcl/Tk embedding and
24remote interfaces with the same application. The files are:
25
26map.readme       -  this file
27mapcolour.tcl    -  the main Tcl code, shared by both interfaces
28mapcolour.ecl    -  the main ECLiPSe code, shared by both interfaces
29mapremote.tcl    -  the remote interface specific code
30mapembed.tcl     -  the embed interface specific code
31
32map_data.map     -  the map data file for a big (110 countries) map
33map_simple.map   -  the map data file for a simple map
34
35The program provides a graphical interface to display the Map Colouring
36problem as the Map is being coloured. The program can use either the fd or
37ic library as the finite domain solver. Either fd_search or ic_search
38library is used to perform the needed search dependending on if fd or ic is
39used as the solver. The options for variable selection and value choice are
40largely those of search/6 in fd/ic_search, except for the `rotate colours'
41value choice, which rotates the order of colour selection for each
42succeeding region.
43
44To run the program using the embedding interface, run mapembed.tcl. 
45
46To run the program using the remote interface, start up an ECLiPSe, and use
47remote_connect/3 to try to establish a remote connection. This will print
48out the host and port address it expects the remote connection to connect
49at. Now run mapremote.tcl, and enter the host and port information. 
50
51On Unix systems, in order to execute the Tcl startup programs, you need to
52set your ECLIPSEDIR environment variable to your ECLiPSe distribution's
53directory (this readme file and all the map colouring related files should
54be in $ECLIPSEDIR/lib_tcl), and then run the startup programs (mapembed.tcl
55or mapremote.tcl) via Tcl's wish. E.g., if you are using bash, sh:
56
57export ECLIPSEDIR=/my/eclipse/distribution
58wish mapembed.tcl
59
60On Windows, you should double click on either mapembed.tcl or mapremote.tcl
61to start the program.
62
63=================================
64Note on the map data file format:
65
66The data consists of valid Prolog terms (which can thus be compiled by
67ECLiPSe), neighbour/2 and country/6.
68
69neighbour/2 specifies the neighbourhood relationship between countries.
70country/6 specifies the shape and position information for the countries.
71This information is used by the ECLiPSe code for colouring the map.
72
73Countries should be numbered consecutively, starting from 0. 
74
75neighbour(1, 5) declares 1 and 5 to be neighbours (neighbour(5, 1) is not
76needed).
77
78country(iN, X1, Y1, X2, Y2) declares a rectangular region (with the lower
79left-hand corner at co-ordinates X1,Y1 and the upper right-hand corner at
80X2,Y2) to be part of country N. A country can be made up of one or more
81rectangular areas. The ECLiPSe code does not directly make use of this
82information, instead it is passed to the external side to construct a
83graphical representation of the map.
84
85
86
87