1.
Introduction
xgridloc is a GTK+ based X Windows application that accepts as
input the Longitude and Latitude of a 'home' position on earth and
calculates its Maidenhead grid locator, or given the Grid Locator
of this position, calculates its Longitude and Latitude. It can
also accept the position or grid locator of a second 'remote' point
on earth and calculate its bearing and distance from the home
location. If xplanet
is installed, it can also display the position of home and remote
locations and the Great Circle path between them, overlayed on the
earth's map.
xgridloc is a software package released under the GNU Public License, in the form of source-code files in the C programming language, developed on a 1.1 GHz Celeron computer running Gentoo Linux 1.2 and using Glade-2 and the GTK+-2.0.6 library.
2.
Installation Requirements
xgridloc requires the GTK+-2.0 library to be installed. Although
xgridloc's GUI was designed and built using Glade-2, and the
'xgridloc.glade' project file is included, some build files
produced by Glade had to be modified so making changes to the GUI
requires that these modifications are preserved. This is especially
true with the 'interface.c' and 'callbacks.c' source files.
If you would like to plot the home and Dx positions and the path between them using xplanet, then you will need to install xplanet and change the permissions of the directories "arcs", "config" and "markers" in the xplanet directory (usually /usr/share/xplanet or /usr/share/local/xplanet) so that all users have access to them. Something like "sudo chmod -R a+rwx /usr/share/xplanet" should do the trick.
Compilation
Please note that I use Arch
Linux which is a "bleeding edge" type distribution, so there
may be compilation and/or run time difficulties if you are using a
relatively old distro. This is mostly true of the basic
dependencies like GTK+ 2 and Glade 2, and there can also be sound
card incompatibility problems at run time.
To compile the package the first time, run the "autogen.sh" script in the package's top directory. The "configure" script as produced by Glade-2 specifies the gcc flags as "-g -O2", but if you want to specify different flags, you will have to run "configure" with the CFLAGS option, e.g. ./configure CFLAGS="-Wall -O2 -march=i686" or whatever flags of your choice.
Run "make" to produce the executable binary in src/. This can then be copied to a suitable location, usually /usr/local/bin or /usr/bin. You can of course run "make install" which will install the binary into /usr/local/bin by default. To recompile the package, you must run 'make distclean' in the top directory to clean up the package and then run the "configure" script.
There is only this hypertext documentation file which you can copy to a location of your choice. You must also copy the default/.xgridlocrc config file to your home directory AND edit it with the details of your home location if xgridloc is to run!
3. Operation
Start xgridloc and enter a position as longitude/latitude in
degrees, minutes and seconds of arc, then press 'Return' to
calculate the grid locator. You may click 'Default Home Position'
to enter the default HOME position from the ~/.xgridlocrc file.
Please note that blank position fields are read as a zero value by
default. The buttons at the right of the Longitude and Latitude
entry fields toggle the East/West and North/South direction
selections.
Enter a Maidenhead grid locator (all six characters, upper case or lower case) and and then type 'Return' to calculate the longitude and latitude of the position. Please note that blank characters in the locator field are not accepted.
To calculate bearing and distance to a second 'Remote' point, enter the longitude and latitude or the grid locator in the second row of entry fields as above. Both short path and long path bearings (in degrees) and distances (in km) along a great circle path are calculated and displayed. If the 'Plot GC Arc in xplanet' button is toggled On, then the Great Circle path from Home to Remote will be plotted on the screen using xplanet, if it is installed.
xgridloc attempts to validate user input as far as possible and a pop-up warning dialog will appear if invalid entries are made in any field. Please note that it may still be possible to enter invalid data since xgridloc does not cover every possible sequence of user actions and entries.
Quit xgridloc by closing the window or clicking 'Quit'.
4. Known bugs and
annoyances
I have fixed all bugs I have found. However the validation of
entries is not very rigid so it is possible to enter invalid data
in a field and do computations with erroneous results.
5. Files
xgridloc was built using 'glade', GTK's menu-driven GUI designer.
Glade produces a number of files in the project's top directory and
some source code files in src/ to create the GUI. In addition there
is just one source file (calculate.c) with all my own additional
code and a header file (xgridloc.h). The 'callbacks.c' file is also
edited with some code to implement the user's input via the
GUI.
6. Version History
Version 0.1 beta is the first public beta release of
xgridloc after bug-fixing and testing locally. It is based on code
from the existing 'gridloc' ncurses application.
Version 0.2 beta is a re-design of xgridloc using Glade-2 and GTK+-2.0. A fairly good user input validation process has also been incorporated.
Version 0.3 The 'invalid entry' pop-up dialog has been changed to conform better with standard design for such dialogs.
Version 0.4 Changed the process of configuring the package for compilation so that Glade's 'autogen' script is used to produce correct symlinks to 'automake' and a suitable 'configure' script.
Version 0.5 From this version on, the 'Home' location's position (Longitude and Latitude) are entered in a run time config file, ~/.xgridlocrc. This file must be edited by the user in a text editor to include his location's data.
Version 0.6 Changed the xplanet command so that home/remote locations are plotted in an X window, instead of the root window. Also arranged for the name of the default location to be replaced by the locator in the xplanet display, when the locator or the geographic co-ordinates of the home location are edited.
Version 0.7 After a bug report from Juha Vierinen regarding seg faulting of xnec2c, my graphical adaptation of NEC2, I changed all "sprintf" commands to "snprintf" to avoid buffer overruns. Following on the above changes, I revised all similar situations in xgridloc source code and changed all "sprintf" commands to "snprintf" just in case. While going through the xgridloc source code, I also fixed some minor bugs like typos and tidied error messages and other aspects of the GUI.
Version 0.8 After a bug report from Pino Zollo ZP4KFX regarding GUI problems with my Hellschreiber program xfhell, I made some changes to the GUI code in most of my GTK2 applications.
Version 0.9 After a bug report from Pino Zollo ZP4KFX, regarding failure of "xdemorse" to start the Morse decoding loop after reading its configuration file, I have modified the functions that read this file so that more detailed error messages are printed if entries are malformed.
7. Copying This software package is released under the GNU Public License. Please see the COPYING file for more details.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details:
31 Jan 2003.Last modified: Sun Feb 9 14:31:21 EET 2003