
Help for the main window of the utproc application.

Questions, comments, or bugs may be sent to Ben Foster
at foster@ucar.edu.

------------------------------------------------------------------------
Selecting TGCM history file(s):

Clicking on the "Select File(s)" button brings up a dialogue for
selecting one or more files from the local disk. Default settings
for the file dialogue are:

- Directory: "/aim/d/tgcm/timegcm1.2_y2d/py2c" (on the HAO file system)
- Filter:    "*.nc"        (netcdf files)

Select files by clicking the left mouse button over the desired
file in the "Files" text box. To select a group of files, select 
the first file, then hold down the shift key and select the last
file. All files in between the first and last selection will be
highlighted. (This assumes a UNIX operating system)

The model times (day,hour,minute) on any group of files must be 
sequentially increasing, with a constant delta-time between histories.
If a single file is selected, there must be more than one history 
on the file.

------------------------------------------------------------------------
Selecting start and end times:

After files have been selected, the model times on all files are
displayed in two scrollable text widgets, one for selecting the
desired start time, and another for the desired ending time to
be plotted.

Default values are the first and last times in the file sequence,
respectively. Use the left mouse button to override these defaults.
The selected start time must be less than the selected end time.

------------------------------------------------------------------------
Selecting fields to plot:

All 4-d variables (lon,lat,lev,time) found on the first file are 
displayed in a scrollable text widget. By default, only the first 
field is selected. An adjacent text widget displays the currently
selected fields. To select additional fields, hold down the "control"
key while selecting with the left mouse button, or hold down the
"shift" key to select a subset of the list.

Selected fields must exist on all files (at least those files 
containing the start and end times). Currently, the application
assumes that 4-d variables found on the first file exist on all 
files, so this is the user's responsibility.

------------------------------------------------------------------------
Selecting the output device:

There are currently two possible output devices: the X display
(i.e., an IDL draw window on your screen), or a postscript file.  
You may select one or the other (not both) by using the two radio 
buttons labeled "X11 Display" and "Postscript". When "Postscript" 
is selected, the current ps output file is displayed in an editable 
text widget labeled "PS output file:" (see below for more information).

You can toggle seamlessly between X and the currently open PS file,
using the radio buttons. When the output device is PS, any generated
plots are appended to the currently open PS file. When the output
device is X, plots are displayed sequentially in the IDL window
(see below for more information).

When the application is started, the default output device is
postscript, and the default ps file is "utproc.ps" in the current
working directory (i.e., the directory from which utproc was started).
NOTE: If the file utproc.ps exists when the application is started, 
it will be truncated, and any former contents will be lost.

You can specify a new PS file by typing in the "PS output file:"
text window. Its best to hit the "return" key to enter the file
name, but this is not necessary. Be aware that when you specify
a new file, the previous PS file will be closed, and IT CANNOT BE 
REOPENED FOR APPENDING. If you specify a file that already exists
and is non-empty, a warning dialogue pop-up will appear giving you 
the choice of either opening and truncating the file, or cancelling 
and reverting to the currently open file.

You can use ghostview to preview the currently open PS file, however
ghostview will hang when displaying the last image in the file until
the file is closed (by starting a new PS file, or exiting the application).

When X is the output device, the first plot will be displayed in an 
IDL window and the cursor will be changed to an hourglass, and all 
utproc widgets are blocked.  To advance to the next plot, place the 
cursor in the plot window (or any utproc window), and click the left 
mouse button. After the last plot of the series is displayed, the cursor 
will revert to an arrow, and utproc widgets will become active again.  

------------------------------------------------------------------------
Control buttons at bottom of the main window:

"Plot ut vs pressure"
Clicking on this button brings up a window in which you can set up 
contour plots with time on the x-axis and pressure on the y-axis. 
You select lat,lon locations to be displayed, and the bottom and
top pressures for the y-axis.
Repeated clicking on this button will bring up additional instances 
of this window, so different sequences of plots can be set up.  
There is a separate help button in this window.

"Plot ut vs latitude"
Clicking on this button brings up a window in which you can set up
contour plots with time on the x-axis and latitude on the y-axis.
You select desired pressure levels and longitudes to be plotted, and 
the latitude range for the y-axis.
Repeated clicking on this button will bring up additional instances 
of this window, so different sequences of plots can be set up.  
There is a separate help button in this window.

"Exit Utproc"
Clicking on this button exits the application. All windows related
to the current instance of the application are destroyed. The current
PS output file is closed.
