xgridloc User Manual

  1. Introduction
  2. Installation
  3. Operation
  4. Known bugs and annoyances
  5. Files
  6. Version History
  7. Copying

1. Introduction
xgridloc is a GTK+-3 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, overloaded 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-3 and the GTK+-3.22 library.

2. Installation
Requirements
xgridloc requires the GTK+-3.22 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 Void 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+-3, and there can also be sound card incompatibility problems at run time.

To compile the package, it may be preferable to first run the included "autogen.sh" script in the package's top directory, to produce a fresh build environment. Then the "configure" script can be run with optional parameters to override the default settings and compiler flags, e.g: ./configure --prefix=/usr CFLAGS="-g -O2" will override the default /usr/local installation prefix and the "-Wall -O2" compiler flags.

Running "make" in the package's top directory should produce the executable binary in src/. Running "make install" will install the binary into /usr/local/bin by default or under the specified prefix. It will also install the default configuration file into the user's home directory. This will have to be edited by the user as required. There is also this hypertext documentation file which you can copy to a location of your choice.

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, in either 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. However, if the last two letters of the locator are not entered, xgridloc will insert LL as a default completion.

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.

Version 1.0 After a feature request by Richard Gordon, KD0BJT, I have arranged for xgridloc to fill the last two letters of the locator code with a default of LL, if only the first four characters are entered.

Version 1.1 After a feature request by Richard Gordon, KD0BJT, I have arranged for xgridloc to display distances in units other than Km. This is done by entering the distance unit name (e.g. "Miles") and the conversion factor (e.g. 0.621371192) into the .xgridlocrc file. I also change the default last characters from LL to MM, which is nearer to the center of the square.

Version 1.2 I rearranged the source files so that each C source file has its own header file. Common entries are now in the common.h file and entries relevant to each source file are in the associated header.
I have also arranged for the xplanet command and config file paths to be in the .xgridlocrc file instead of the common header file.

Version 1.3 Fixed a bug reported by Richard Gordon KD0BJT: Although I arranged for the xplanet command and config file paths to be in the .xgridlocrc file, I overlooked the code that writes these paths in the xplanet config file. As a result, if the file path to the marker and arc files was changed in .xgridlocrc, from the default paths of xplanet, then the xplanet config was not updated by xgridloc.

Version 1.4 I have updated the basic files of the GNU Autotools build system, to be compatible with the current version of these tools at the time of writing (February 2013).

Version 1.5 I have fixed a number of defects reported by the source code auditing tools of the Coverity Scan website. These were mainly related to programming practices and did not affect the operation of this application.

Version 1.6 I have modified the file parser code so that it can read the config file with both the '.' and ',' as decimal point characters. This is necessary to make xgridloc compatible with different locales.

Version 1.7: I made some changes to the Strlcat() function and its usage in the xgridloc code, to improve safe handling of string concatenation operations. Hopefully this has not broken the handling of various strings in xgridloc! ;-)

Version 1.8: I updated the GUI code to the latest GTK+-3.22. This made it necessary to make minor changes to the User Interface but functionality remains the same. An advantage of this version is that the GUI specification is in a Glade-3 XML file in the ~/.xgridloc/ folder (xgridloc.glade), and this can be edited in Glade-3 if some cosmetic changes are desired. Also I migrated the internationalization system from "intltoolize" to GNU GetText, as the former is now considered obsolete.

Version 1.8.1: I edited Makefile.am so that make install will now place relevant application files (documentation, pixmaps, desktop file, glade UI file etc) into the right places.

Version 1.8.2: I changed the code that invokes xplanet since the original tested the pkill() command's return value for errors and invoked an error condition on the failure of pkill(). However pkill() would fail at the first attempt to display the great circle paths between the two locators, since there would not have been an instance of xplanet to kill.

Version 1.8.3: Changed the installation commands in Makefile.am so that all the relevant files (desktop file, application pixmap, configuration file, executable binary etc) are installed under any location specified to the configure script by the --prefix= option. Also modified the program so that on first start up after installation, the application will create its working directory by copying files from the relevant directories under the installation prefix.

Version 1.8.4: After a suggestion from Jaroslav Skarvata, OK2JRQ, maintainer of xgridloc for the Fedora distribution, I applied patches provided by him to make the installation of xgridloc compatible with modern standards and with the Fedora distribution.

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.