	$Id: README.xgrid,v 1.4 2009/09/09 23:27:05 guru Exp $

Distributed under the GNU Public License (see file ../LICENSE.TXT)

Hugh Fisher (hugh@cres.anu.edu.au)
March 1992
					
  I'm leaving CRES at the end of March, so please
  consider this a gift and modify it as you please.

		Source Code
		-----------

  Requires Athena widget set, Release 4.
  
  The makefile has some odd directory specifications
  due to the peculiarities of our local system.
  
  The code varies in style because I wrote this over
  a three month period in my spare time.

  Main control code.
    
    xGridEdit.c
    The application skeleton.
  
    view.h/.c
    Creates the display widget, opens and
    saves the grid file.

    textView.h/.c
    Displays the grid values and handles the mouse.
  
    textInput.h/.c
    Handles entry of new values.

  GMT grid code.
  
    grid.h
    GMTgrid.h
    GMTgrid.c
  
    I had some ideas of making this a general
    purpose grid editor that could handle ascii
    files as well, so this is a overly abstract
    grid representation type and the GMT
    implementation. Could be simplified to a
    single module.
    
 Generic X Windows code.
 
    messages.h/.c
    General purpose message/status line for
    applications that I write.
    
    controls.h/.c
    General purpose application control bar.
    
    Canvas.h/P.h/.c
    Panner.h/P.h/.c
    Two application widget classes that I
    use a lot. Canvas is a generic workspace
    widget. Panner is a scrolling controller
    which I wrote because a) the Athena viewport
    can't handle very large views and b) I
    don't like the way Athena scrollbars work.
  
    Xutility.h/.c
    As the name says, X Windows utility functions.

Bits and pieces.

    utility.h/.c
    General purpose code.
    
		Using xGridEdit
		---------------

  XGridEdit is an application for viewing and editing
  the numerical values in GMT 2 dimensional grids.

  Usage: xgridedit <filename>
  You can use all the standard X command line options.

  It displays the numerical values in a spreadsheet
  like grid. The values shown are the raw values,
  not scaled.

  The display can be scrolled with the modified
  Athena scrollbars. The middle button drags the
  thumb. The left and right buttons scroll by a
  "page" which is by default 90% of the window.
	
  To edit a value, click on it with any button. The
  entry field in the control bar will become active.
  Retype the value and press Return or Tab to
  enter it in the grid. (xGridEdit redirects key
  events to the input area so you don't need to
  move the mouse over or click on it.)

  The Undo button will cancel the most recent edit.

  The Save button, surprise, prompts you for a
  file name to save the grid as. Choosing Discard
  cancels it.

  The Quit button will first ask if you want to
  save if there are any unsaved changes.

  Files are opened, read/written, and closed rather
  than being kept open during execution.

Preferences

  Resources for the display canvas are:
  
  showGrid	Boolean. Controls whether grid lines
  		are drawn. Default is True.
  gridColor	Pixel. The grid line color. Default
  		is Light blue.
  valueColor	Pixel. Color for values. Default is
  		the widget foreground color.
  margin	Integer. The number of pixels to leave
  		around each value. Default is 4.
  precision	String. The number of digits and
  		decimal places to show. Default is "5.2"

  The main display is a Panner widget called "view"
  with two scrollbar children and a Canvas widget
  for actual display. The canvas widget name is derived
  from the file name by stripping off the directories
  and any "." extensions. To specify a precision for
  all grids, use
  	...view*precision:
  To specify a precision for file data/sample.cdf,
  	...sample.precision:
  
  The actions and translations for the display canvas
  are
  	<MotionNotify>:	CursorMovement()
	Highlights the value under the mouse and
	shows the coordinates in the message line.
	
	<LeaveNotify>: ClearMessage()
	Just clears the coordinates from the message line.
	
	<BtnDown>: SelectValue()
	This selects the value under the mouse for editing.

  The control bar is named "control." The buttons are
  named "quit", "save", and "undo." All the application
  code is in callbacks triggered by the notify action
  on the buttons.
  
  The input field is a box widget named "input" with a
  label "prompt" and ascii text widget "field." The
  text widget has one action, EnterNewValue(), which
  is bound to Tab and Return. 

 
8/5/93
The following changes were made to the original xgridedit distribution at
NOAA's Geosciences Lab. by W.H.F. Smith and J.L. Lillibridge III for GMT_2.1.4:

1) A bug in GMTgrid.c caused core dumps when referencing grdfile values
   that were "out of bounds".  This was traced to a typo in routine "get"
   near the end of GMTgrid.c. A reference to "grid->header.ny" should
   have been to "grid->header.nx".

2) To make GMTgrid.c more generic, the "isnan" function (not available on
   SGIs) was replaced with the GMT macro "bad_float". This was added into
   GMT_grid.h.  We would have preferred to simply "#include gmt.h" in
   GMT_grid.h, but conflicting definitions prevented this being done easily.

3) The makefile had leading <TAB> characters that caused problems, these were
   removed.  The proper LDFLAGS for both Suns and SGIs have been included.
   Other platforms may need to make changes to the LDFLAGS as well.

4/4/95:	PW: Can only read GMT netcdf-format grdfiles

10/14/98: PW: Now uses GMT_is_nan macro.  Compiles for GMT 3.1

05/25/2000: Lloyd Parkes: Now uses autoconf to determine X libs and
		uses GMT to read the gridfiles.

14/09/2007: Remko Scharroo: Compiler info for X now comes from ../makegmt.macros
