/*
 **&GRCFIL -- Close file from GRFILEIO access
 *+
 *     FUNCTION GRCFIL (FD)
 *     INTEGER GRCFIL (FD)
 *
 * Closes the file with descriptor FD from GRFILEIO access. GRCFIL returns
 * 0 when properly closed. Otherwise, use PERRORF to report the error.
 *
 * Usage:
 *      IOS = GRCFIL (FD)
 * or:
 *      CALL GRCFIL (FD)
 *
 * In the last case the return code is ignored.
 *
 * Arguments:
 *  FD      (input) : File descriptor returned by GROFIL.
 *  GRCFIL (output) : Error code or 0 on proper closing.
 *-
 */


/*
 **&GRWFIL -- GRFILEIO write routine
 *+
 *     FUNCTION GRWFIL (FD, NBYTE, BUFFER)
 *     INTEGER FD, NBYTE, GRWFIL
 *     BYTE    BUFFER(NBYTE)
 *
 * Writes NBYTE bytes into the file associated by descriptor FD (which is
 * returned by the GROFIL call. The array BUFFER contains the data that has
 * to be written, but can (of course) also be associated with any other
 * string, scalar, or n-dimensional array.
 * The function returns the number of bytes actually written in GRWFIL. If
 * GRWFIL < 0, a write error occurred.
 *
 * Arguments:
 *  FD      (input) : File descriptor returned by GROFIL
 *  NBYTE   (input) : Number of bytes to be written
 *  BUFFER  (input) : Buffer containing the bytes that have to be written
 *  GRWFIL (output) : Number of bytes written, or (if negative) error code.
 *-
 */


/*
 **&GRWFCH -- GRFILEIO write FORTRAN character STRING routine
 *+
 *     FUNCTION GRWFCH (FD, STRING)
 *     INTEGER FD, GRWFCH
 *     CHARACTER*(*) STRING
 *
 * Writes NBYTE bytes into the file associated by descriptor FD (which is
 * returned by the GROFIL call). The string STRING contains the data that has
 * to be written.
 * The function returns the number of bytes actually written in GRWFCH. If
 * GRWFCH < 0, a write error occurred.
 *
 * Arguments:
 *  FD      (input) : File descriptor returned by GROFIL
 *  STRING  (input) : String containing the characterst to be written
 *  GRWFCH (output) : Number of bytes written, or (if negative) error code.
 *-
 */


/* Open a channel to the device specified by 'cdev'.
 *
 * cdev      I    The name of the device to be opened
 * ldev      I    Number of valid characters in cdev
 * groter    O    The open channel number (-1 indicates an error)
 */


/* Close a previously opened channel.
 *
 * fd        I    The channel number to be closed
 */


/* Write lbuf bytes from cbuf to the channel fd.  Data is written without
 * any formating.
 *
 * fd        I    The channel number
 * cbuf      I    Character array of data to be written
 * lbuf      I/O  The number of bytes to write, set to zero on return
 */


/* Write prompt string on terminal and then read response.  This version
 * will try to read lbuf characters.
 *
 * fd        I    The channel number
 * cprom     I    An optional prompt string
 * lprom     I    Number of valid characters in cprom
 * cbuf      O    Character array of data read
 * lbuf    I/O    The number of bytes to read, on return number read
 */


/* supported by X Window */


/* The parseops routine parses command line arguments */


/* The mergeops routine merges the command line options in with all the */
/* resource files */


/* Sam Southard, Jr. */
/* Created: 22-Apr-1993 */


/* The pggcurs and bmcurs routines get the first cursor event in the line */
/* graphics or bitmap graphics list and returns it in the buffer buf, which */
/* has the format for the BM_GET_CURS and LG_CURS commands. */
/* Return Values: */
/* Whatever getcurs returns */


/* The pgscurs routine sets the current line graphics cursor position.  Note */
/* that this does not do anything unless there are no entries in the list of */
/* cursor events and does not do anything visible unless this position is */
/* different than the previousrecorded line graphics cursor location. */


/* The bmscurs routine sets the current bitmap graphics cursor position.  */
/* Note that this does not do anything unless there are no entries in the */
/* list of cursor events and does not do anything visible unless this */
/* position is different than the previous recorded line graphics cursor */
/* location. */


/* The clearcurs routine clears all the cursor events from both lists. */


/*----------------------------------------------------------------------
 * Demonstration function for PGPLOT contouring routines.
 *--------------------------------------------------------------------*/


/*.......................................................................
 * Extract marked prototypes from a given file, decode them, and
 * optionally write wrapper file(s) and append prototypes to the library
 * header file.
 *
 * Input:
 *  pg     PGbind *   The pgbind state container.
 *  fname    char *   The name of the file to be processed, or NULL to
 *                    select stdin.
 * Output:
 *  return    int     0 - OK.
 *                    1 - Error.
 */


/*.......................................................................
 * Display program usage information on stderr.
 *
 * Output:
 *  return   int   EXIT_FAILURE - For use as exit() argument.
 */


/*.......................................................................
 * Create a new state container for a specified system.
 *
 * Input:
 *  argc       int    The number of command-line arguments in argv[].
 *  argv      char ** Array of command-line arguments.
 * Output:
 *  return  PGbind *  The initialized container, or NULL on error.
 */


/*.......................................................................
 * Cleanup and delete a PGbind state container.
 *
 * Input:
 *  pg     PGbind *  A container allocated by new_PGbind().
 * Output:
 *  return PGbind *  Allways NULL.
 */


/*.......................................................................
 * Search and read the next prototype from the current lexical analyser
 * input file. Prototypes are distinguishable by the FORTRAN comment prefix:
 * string assigned to PG_PREFIX (defined at the top of this file).
 *
 * Input:
 *  lex      Lex *  The lexical analyser state container.
 * Output:
 *  return   int    0 - The prototype has been copied succesfully into
 *                      lex->prototype[].
 *                  1 - No prototype found.
 */


/*.......................................................................
 * Decode the prototype in pg->fn.prototype[] into a function name and
 * arguments.
 *
 * Input:
 *  lex      Lex *  The lexical analyser state container.
 * Input/Output:
 *  fn  Function *  The container in which to record the function
 *                  information.
 * Output:
 *  return   int    0 - OK.
 *                  1 - Error.
 */


/*.......................................................................
 * Given the initialized descriptor pg->fn, write a C prototype in the
 * new header file, that is open for write in pg->hfile.
 *
 * Input:
 *  hfile    FILE *  The file pointer to a header file opened for writing.
 *  fn   Function *  THe descriptor of the function to be prototyped.
 * Output:
 *  return    int    0 - OK.
 *                   1 - Error.
 */


/*.......................................................................
 * Given the initialized descriptor pg->fn, write a C wrapper file.
 *
 * Input:
 *  sys   Sysattr *  A list of system attributes.
 *  fn   Function *  The descriptor of the function to be written.
 * Output:
 *  return  int    0 - OK.
 *                 1 - Error.
 */


/*.......................................................................
 * Report a lexical error along with the context of the lexical offset
 * in to the prototype being decoded.
 *
 * Input:
 *  lex    Lex *  The lexical analyser state container.
 *  msg   char *  The error message.
 *  next   int    If true, the context of the error is the next token,
 *                as pointed to by lex->next, otherwise it is the last
 *                token read, a pointed to by lex->last.
 * Output:
 *  return int    Allways 1. This intended to be used where the error
 *                return value of the parent function is 1, such that
 *                the caller can type  return lex_error(lex,"...",1);
 */


/*.......................................................................
 * Attempt to read a type name via the lexical analyser from the next
 * unprocessed part of the prototype string, and match it with
 * a Typecode enumeration identifier.
 *
 * Input:
 *  lex         Lex *  The lexical analyser state container.
 * Output:
 *  return Typecode    The data-type read. On error DAT_NONE is returned
 *                     but no error message will have been emitted.
 */


/*.......................................................................
 * Attempt to read an identifier name via the lexical analyser from the
 * next unprocessed part of the prototype string, and return a pointer
 * to a '\0' terminated copy of it, placed in the next unused
 * part of lex->buffer[].
 *
 * Input:
 *  lex         Lex *  The lexical analyser state container.
 * Output:
 *  return Typecode    The data-type read. On error DAT_NONE is returned
 *                     but no error message will have been emitted.
 */


/*.......................................................................
 * Return the type name associated with a Typecode enumerator.
 *
 * Input:
 *  type  Typecode    The enumeration identifier to return the name of.
 * Output:
 *  return    char *  The name of the associated type, or NULL on error.
 */


/*.......................................................................
 * Return the pointer cast for the type associated with a Typecode enumerator.
 *
 * Input:
 *  type  Typecode    The enumeration identifier to return the name of.
 * Output:
 *  return    char *  The required cast in the form "(type *)".
 */


/*.......................................................................
 * Advance over the next un-processed character of a prototype and
 * any trailing spaces up to the start of the next token.
 *
 * Input:
 *  lex    Lex *  The lexical analyser state container.
 */


/*.......................................................................
 * Look up a command line option by name.
 *
 * Input:
 *  name     char *  The name of the option to look up.
 * Output:
 *  return Optype    The enumeration identifier of the new type, or
 *                   OP_NONE if not recognised.
 */


/*.......................................................................
 * A utility function to write a given number of spaces to a given
 * stream.
 *
 * Input:
 *  nspace   int   The number of spaces to be written.
 */


/*.......................................................................
 * Take a single line and wrap it into multiple lines, with an optional
 * margin.
 *
 * Input:
 *  stream  FILE *  The stream to write to.
 *  string  char *  The string to be wrapped.
 *  start    int    The length of the existing pefix on the first line.
 *                  This will be padded up to 'margin' with spaces.
 *  margin   int    The number of characters to pad with spaces
 *                  before writing each line.
 *  nmax     int    The number of characters per line.
 * Output:
 *  return   int    The number of characters used on the last line.
 *                  This can be used to break up a single call to wrap_line()
 *                  into multiple calls, by suplying the return value of the
 *                  previous call as the 'start' column value for the next call.
 */


/*.......................................................................
 * Write a FORTRAN symbol name in the form that the local FORTRAN
 * compiler is purported to export it to the linker.
 *
 * Input:
 *  stream   FILE *  The stream to write the name to.
 *  sys   Sysattr *  A list of system atributes.
 *  name     char *  The symbol name.
 */


/*.......................................................................
 * Initialize a system attributes container with default values.
 *
 * Input:
 *  sys   Sysattr *  The container to be initialized.
 */


/*.......................................................................
 * Create a new lexical analyser state descriptor connected to stdin.
 *
 * Output:
 *  return   Lex *  The initialized descriptor, or NULL on error.
 */


/*.......................................................................
 * Delete a Lex descriptor and its contents. This includes closing any
 * file that is assigned to it.
 *
 * Input:
 *  lex    Lex *  A descriptor previously allocated by new_Lex().
 * Output:
 *  return Lex *  Allways NULL.
 */


/*.......................................................................
 * Re-connect a lexical analyser to a new input file.
 *
 * Input:
 *  lex      Lex *   The lexical analyser descriptor.
 *  fname   char *   The name of the file to be opened, or NULL to
 *                   select stdin.
 * Output:
 *  return   int     0 - OK.
 *                   1 - Error.
 */


/*.......................................................................
 * Read a new line from a lexical analyser input file.
 *
 * Input:
 *  lex      Lex *  The lexical analyser descriptor.
 * Output:
 *  return  char *  Pointer to the buffer lex->buffer[] containing the
 *                  line read, or NULL on EOF or other error.
 */


/*.......................................................................
 * This is the only external entry point to the /gwm device driver.
 * It is called by PGPLOT to open, perform operations on, return
 * information about and close /gwm windows.
 *
 * Input:
 *  ifunc   int *  The PGPLOT operation code to be executed.
 * Input/output:
 *  rbuf  float *  A general buffer for input/output of float values.
 *  nbuf    int *  Where relevant this is used to return the number of
 *                 elements in rbuf[]. Also used on input to specify
 *                 number of pixels in the line-of-pixels primitive.
 *  chr    char *  A general buffer for string I/O.
 *  lchr    int *  Where relevant this is used to send and return the
 *                 number of significant characters in chr.
 * Input:
 *  mode    int *  Device specific mode parameter - currently unused
 *  len     int    Added to the call line by the FORTRAN compiler.
 *                 This contains the declared size of chr[].
 */


/*.......................................................................
 * Assign a given RGB color representation to a given color index.
 *
 * Input:
 *  gwm   GWMdev *  The /gwm device descriptor.
 *  ci      int    The color index to assign the color to. Out of range
 *                 indexes are quietly ignored.
 *  red   float    The fractional red brightness 0..1.
 *  green float    The fractional green brightness 0..1.
 *  blue  float    The fractional blue brightness 0..1.
 * Output:
 *  return  int    0 - OK.
 *                 1 - Error.
 */


/*.......................................................................
 * Map floating point color intenisties between 0.0 and 1.0 to XColor
 * intensities between 0 to 65535. Numbers outside of this range are
 * limited to the nearest of the two limits.
 *
 * Input:
 *  rgb              float   The PGPLOT normalized intensity to be converted.
 * Output:
 *  return  unsigned short   The equivalent XColor RGB intensity.
 */


/*.......................................................................
 * Map XColor intensities between 0 and 65535 to floating point color
 * intenisties between 0.0 and 1.0. Numbers outside of this range are
 * limited to the nearest of the two limits.
 *
 * Input:
 *  unsigned short   The equivalent XColor RGB intensity.
 * Output:
 *  return   float   The PGPLOT normalized intensity to be converted.
 */


/*.......................................................................
 * Flush color-representation changes made by gwm_set_rgb() to the /gwm
 * window. This updates the window colormap. If color index 0 is changed
 * then the background color is also updated.
 *
 * Input:
 *  gwm     GWMdev *    The PGPLOT /gwm device descriptor.
 *  If gwm->color.nbuff > 0 {
 *    For(ci=gwm->color.sbuff; ci<gwm->color.sbuff + gwm->color.nbuff; ci++) {
 *      gwm->color.pixel[ci] = Color pixel to be changed.
 *      gwm->color.xcolor[ci]= Requested color representation.
 *    }
 *  }
 * Output:
 *  If gwm->color.nbuff > 0 {
 *    For(ci=gwm->color.sbuff; ci<gwm->color.sbuff + gwm->color.nbuff; ci++) {
 *      gwm->color.pixel[ci] = New color pixel if the colormap is readonly.
 *      gwm->color.xcolor[ci]= Actual color representation installed.
 *    }
 *  }
 *  return    int      0 - OK.
 *                     1 - Error.
 */


/*.......................................................................
 * Initialize the color representations in the color table.
 *
 * Input:
 *  gwm     GWMdev *    The PGPLOT /gwm device descriptor.
 * Output:
 *  gwm->color.xcolor[0..ncol] The color pixel definitions.
 *  return    int      0 - OK.
 *                     1 - Error.
 */


/*.......................................................................
 * Create two cursors. One cursor is for the main gwm window when
 * cursor input is not possible.  The other is used by the InputOnly
 * window which overlays the output window and is used for cursor
 * input.
 *
 *  gwm        GWMdev * The PGPLOT /gwm device descriptor.
 *
 * Output:
 *  return     int   0 - OK.
 *                   1 - Error.
 */


/*.......................................................................
 * Clear the window and pixmap to start a new page.
 *
 * Input:
 *  gwm   GWMdev *  The PGPLOT /gwm device descriptor.
 * Output:
 *  return  int    0 - OK.
 *                 1 - Error.
 */


/*.......................................................................
 * Set the foreground color.
 *
 * Input:
 *  gwm   GWMdev *  The PGPLOT /gwm device descriptor.
 *  ci      int    The PGPLOT color index to instate as the foreground
 *                 color.
 * Output:
 *  return  int    0 - OK.
 *                 1 - Error.
 */


/*.......................................................................
 * Update the vertices of the rectangular area that has been modified
 * since the last time the window was updated from the pixmap.
 *
 * Input:
 *  gwm     GWMdev * The PGPLOT /gwm device descriptor.
 *  x         int   The x-axis pixel index that the rectangular update area
 *                  must be extended to include.
 *  y         int   The y-axis pixel index that the rectangular update area
 *                  must be extended to include.
 *  diameter  int   The diameter of the locus in pixels. For line or
 *                  point drawing operations this is usually the line width.
 */


/*.......................................................................
 * Flush changes to the pixmap to the window.
 *
 * Input:
 *  gwm   GWMdev *  The PGPLOT /gwm device descriptor.
 * Output:
 *  return  int    0 - OK.
 *                 1 - Error.
 */


/*.......................................................................
 * Open a /gwm window and return an initialized /gwm PGPLOT device descriptor.
 *
 * Input:
 *  gwm_name  char *   A string containing the name of the GWM window.
 *  mode        int     The type of window to open.
 *                       Unused at present
 * Output:
 *  return    GWMdev *   THe PGPLOT /gwm device descriptor, or NULL on error.
 */


/*.......................................................................
 * Delete a PGPLOT /gwm device and its descriptor.
 *
 * Input:
 *  gwm      GWMdev *  The descriptor of the device to be deleted.
 *  partial   int    0 - Normal deletion - delete everything.
 *                   1 - Close the display connection and mark all
 *                       resources as deleted but don't delete the
 *                       container - also set gwm->bad_device==1.
 * Output:
 *  return  GWMdev *  Allways NULL. Use like gwm = del_GWMdev(gwm,0);
 */


/*.......................................................................
 * Before using a given /gwm device descriptor call this function to check
 * that it is usable. If it isn't, 0 will be returned and you should not
 * attempt to use the descriptor. If the descriptor is NULL an error
 * message will be presented.
 *
 * Input:
 *  gwm      GWMdev *  The device descriptor to be checked.
 * Output:
 *  return     int    1 - Descriptor OK.
 *                    0 - Error - don't use /gwm.
 */


/*.......................................................................
 * Present the active cursor, wait for the user to press a button or
 * keyboard key, then retrack the active cursor and return the cursor
 * position and key pressed.
 *
 * Input:
 *  gwm   GWMdev *   The PGPLOT /gwm device descriptor.
 *  mode    int     0 - No rubber banding.
 *                  1 - Maintain a rectangle outline with opposing
 *                      vertexes at (xin,yin) and the cursor.
 *                  2 - Maintain a line between (xin,yin) and the cursor.
 *  posn    int     0 - Don't attempt to position the cursor.
 *                  1 - Do try to pre-position the cursor.
 *  ref  XPoint *   The reference position of the cursor (can be the same
 *                  as 'pos').
 * Input/Output:
 *  pos  XPoint *   The start position of the cursor. On output this is the
 *                  selected position of the cursor.
 * Output:
 *  key    char *   If key!=NULL, the selection key will be assigned to
 *                  the caller's variable pointed to by key.
 *  return  int     0 - OK.
 *                  1 - Error.
 */


/*.......................................................................
 * This is a private function of gwm_read_cursor(). Create an InputOnly
 * window which overlays (and is a child of) the main gwm window. This
 * is used to read the cursor as another application may be soliciting
 * ButtonPress events in the gwm window itself.
 *
 * Input:
 *  gwm          GWMdev *  The PGPLOT /gwm device descriptor.
 *
 * Output:
 *  return         int    0 - OK.
 *                        1 - Error.
 */


/*.......................................................................
 * This is a private function of gwm_read_cursor(). If the user has just
 * pressed one of the keyboard or keypad arrow keys, it moves the cursor
 * by one pixel in the corresponding direction. If one of the shift keys
 * is also held down, then the cursor is moved by ARROW_KEY_VELOCITY
 * pixels instead of one. If the resulting shift would move the cursor
 * out of the bounds of the pgplot window pixmap, then the motion is
 * aborted.
 *
 * Input:
 *  gwm          GWMdev *  The PGPLOT /gwm device descriptor.
 *  keysym      KeySym    The key symbol returned by XLookupString() wrt
 *                        the arrow-button key-press.
 *  modifiers unsigned    The Event::xkey.state key-modifier mask
 *                        associated with the key-press.
 * Output:
 *  return         int    0 - OK.
 *                        1 - Error.
 */


/*.......................................................................
 * Private return function of gwm_read_cursor().
 *
 * Input:
 *  gwm   GWMdev *   The PGPLOT /gwm device descriptor.
 *  bc     Band *   The cursor banding descriptor to be deleted.
 *  status  int     Required gwm_read_cursor() return status.
 * Output:
 *  return  int     The value of 'status'.
 */


/*.......................................................................
 * Convert from the coordinates sent by PGPLOT in rbuf[...] to an
 * X-windows point in the coordinate system of the window.
 *
 * Input:
 *  gwm     GWMdev *   The PGPLOT /gwm device descriptor.
 *  xy      float [2] Array of two floats containing PGPLOT coordinates
 *                    arranged as x followed by y.
 * Output:
 *  xp     XPoint *   The converted coordinates will be assigned to xp->x
 *                    and xp->y.
 */


/*.......................................................................
 * Convert from window pixel coordinates to PGPLOT coordinates, in a
 * form that can be returned to PGPLOT via rbuf[...].
 *
 * Input:
 *  gwm     GWMdev *   The PGPLOT /gwm device descriptor.
 *  xp     XPoint *   The window pixel-coordinates to be converted.
 * Output:
 *  xy      float [2] Output array of two floats in which to place the
 *                    PGPLOT coordinates, arranged as x followed by y.
 */


/*.......................................................................
 * Draw a horizontal line of pixels at a given location, from a float
 * array of PGPLOT color indexes.
 *
 * Input:
 *  gwm     GWMdev *   The PGPLOT /gwm device descriptor.
 *  start  XPoint *   The position to start the line at.
 *  cells   float *   An array of ncell pixel PGPLOT color indexes.
 *  ncell     int     The number of cells in cells[].
 * Output:
 *  return    int     0 - OK.
 *                    1 - Error.
 */


/*.......................................................................
 * Call this function when an Expose event is received. It will then
 * re-draw the exposed region from the gwm->pixmap.
 *
 * Input:
 *  gwm      GWMdev *  The PGPLOT /gwm device descriptor.
 *  event   XEvent *  The expose event.
 * Output:
 *  return     int    0 - OK.
 *                    1 - Error.
 */


/*.......................................................................
 * Set up for a band cursor and return its descriptor.
 *
 * Input:
 *  gwm   GWMdev *   The PGPLOT /gwm device descriptor.
 *  mode    int     0 - No band cursor.
 *                  1 - Line between reference position and cursor.
 *                  2 - Rectangle drawn with opposite corners at reference
 *                      and cursor position.
 *  ref  XPoint *   The reference position.
 * Output:
 *  return Band *   A pointer to a static internal container of cursor
 *                  resources. Call gwm_del_Band() to release these resources
 *                  and return the event mask to normal.
 */


/*.......................................................................
 * Release band cursor resources and return the window event mask to
 * its normal state.
 *
 * Input:
 *  gwm   GWMdev *   The PGPLOT /gwm device descriptor.
 *  bc     Band *   The band-cursor descriptor.
 * Output:
 *  return Band *   Always NULL.
 */


/*.......................................................................
 * Trim a coordinate to lie within the current pixmap and window area.
 * This prevents the cursor being displayed or returned for a position
 * outside the currently visible window and pixmap areas.
 *
 * Input:
 *  xp    XPoint *   The point to be limited.
 * Output:
 *  return   int     0 - OK.
 *                   1 - Error.
 */


/*.......................................................................
 * Draw the current cursor.
 *
 * Input:
 *  gwm  GWMdev *   The PGPLOT /gwm device descriptor.
 *  bc    Band *   A cursor descriptor returned by gwm_new_band().
 *  end XPoint *   The current cursor position.
 * Output:
 *  return int     0 - OK.
 *                 1 - Error.
 */


/*.......................................................................
 * Erase a previously drawn cursor.
 *
 * Input:
 *  gwm  GWMdev *   The PGPLOT /gwm device descriptor.
 *  bc    Band *   A cursor descriptor returned by gwm_new_band().
 * Output:
 *  return int     0 - OK.
 *                 1 - Error.
 */


/*.......................................................................
 * Restore the pixels under a given line.
 *
 * Input:
 *  gwm   GWMdev *  The PGPLOT /gwm device descriptor.
 *  xa, ya  int    The start pixel of the line.
 *  xb, yb  int    The end pixel of the line.
 * Output:
 *  return  int    0 - OK.
 *                 1 - Error.
 */


/*.......................................................................
 * Add to the set of events to be caught.
 *
 * Input:
 *  gwm   GWMdev *  The PGPLOT /gwm device descriptor.
 *  events long    The bit mask of events to be added to those already
 *                 being selected.
 * Output:
 *  return  int    0 - OK.
 *                 1 - Error.
 */


/*.......................................................................
 * Remove selected events from the set of events to be caught.
 *
 * Input:
 *  gwm   GWMdev *  The PGPLOT /gwm device descriptor.
 *  events long    The bit mask of events to be removed from the set
 *                 being selected.
 * Output:
 *  return  int    0 - OK.
 *                 1 - Error.
 */


/*.......................................................................
 * This function is called by X whenever a non-fatal error occurs
 * on a given display connection.
 *
 * Input:
 *  display    Display *  The display connection on which the error occured.
 *  event  XErrorEvent *  The descriptor of the error event.
 * Output:
 *  return         int    The return value is not specified by Xlib, so
 *                        we will simply return 0.
 */


/*.......................................................................
 * Front end to XNextEvent() to get the next event from the X server,
 * while checking for DestroyNotify events on the PGPLOT window.
 *
 * Input:
 *  gwm     GWMdev *  The PGPLOT /gwm device descriptor.
 * Input/Output:
 *  event  XEvent *  The event structure for the returned event.
 * Output:
 *  return    int    0 - OK.
 *                   1 - The PGPLOT window has been destroyed.
 */


/*.......................................................................
 * Front end to XCheckWindowEvent() to check and return for the next event
 * that matches the given event_mask, without blocking if no matching event
 * is there and while also checking for DestroyNotify events on said window.
 *
 * Input:
 *  gwm       GWMdev *  The PGPLOT /gwm device descriptor.
 *  window   Window    The window on which to watch for events.
 *  event_mask long    The bit mask of event types wanted.
 * Input/Output:
 *  event    XEvent *  The event structure for the returned event.
 * Output:
 *  return      int    0 - No matching event.
 *                     1 - Got an event that matches the mask.
 */


/*.......................................................................
 * Remove a given PGPLOT /gwm device descriptor from the list of open
 * devices.
 *
 * Input:
 *  gwm      GWMdev *  The PGPLOT /gwm device descriptor to be removed.
 * Output:
 *  return   GWMdev *  The removed descriptor.
 */


/*.......................................................................
 * Select a given device by its PGPLOT window number: gwm->number.
 *
 * Input:
 *  number      int   The device number to search for.
 * Output:
 *  return   GWMdev * The descriptor of the located device, or NULL
 *                    on error.
 */


/*.......................................................................
 * After a fatal error has occured, this function should be called to
 * mark the specified device as unusable. It emits an error message
 * and sets gwm->bad_device=1.
 *
 * Input:
 *  gwm     GWMdev *  The descriptor of the device on which the error
 *                   occurred.
 * Output:
 *  gwm->bad_device   This flag is set to 1.
 *  return    int    Allways 1 (intended as a boolean to say that the
 *                   device is unusable). This can be used as the return
 *                   value for functions that use 1 to denote an error
 *                   return. eg.
 *                     if(error_occurred)
 *                       return gwm_bad_device(gwm);
 */


/*.......................................................................
 * If the cursor is within the plot window, warp it to a given position.
 *
 * Input:
 *  gwm   GWMdev * The PGPLOT /gwm device descriptor.
 *  pos  XPoint * The location to warp the pointer to if 'warp' is true
 *                and the cursor is in the window.
 *  warp    int   If true, and the cursor is in the window, warp the
 *                cursor to position 'pos'.
 * Output:
 *  loc  XPoint * The located position of the cursor, if it is in
 *                the window.
 *  return  int   0 - Cursor not in window - 'loc' is unchanged.
 *                1 - Cursor is in window - 'loc' records the position.
 */


/*.......................................................................
 * Return a dynamically allocated visual info structure for a given
 * visual. This is simply a more convenient interface to XGetVisualInfo()
 * and XVisualIDFromVisual().
 *
 * Input:
 *  display    Display *   The display connection to which the visual
 *                         belongs.
 *  screen         int     The screen to which the visual belongs.
 *  visual      Visual *   The visual for which information is required.
 * Output:
 *  return XVisualInfo *   The required information descriptor, or NULL
 *                         on error.
 */


/*.......................................................................
 * Allocate the contents of gwm->image. This contains buffers used to
 * construct and dispatch line-of-pixel images to the display.
 *
 * Input:
 *  gwm   GWMdev * The PGPLOT /gwm device descriptor.
 *  npix    int   The length of the buffer in pixels.
 * Output:
 *  return  int   0 - OK.
 *                1 - Error.
 */


/*.......................................................................
 * Limit pixmap coordinates to lie within the pixmap area.
 *
 * Input:
 *  gwm     GWMdev *  The PGPLOT window context.
 * Input/Output:
 *  coord  XPoint *  The coordinates to be modified.
 */


/*.......................................................................
 * Scroll a rectanglular area vertically and/or horizontally.
 *
 * Input:
 *  gwm    GWMdev *  The PGPLOT window context.
 *  rbuf     float *  The array of float arguments sent by the PGPLOT
 *                    GREXEC() subroutine.
 */


/*.......................................................................
 * Output a formatted /gwm driver error message
 *
 * Input:
 *  char *buff   The error message.
 * Output:
 *  None.
 */


/*.......................................................................
 * Define a given executable as a DCL foreign command. This has to be
 * done before the program can be run with command-line arguments.
 *
 * Input:
 *  file    char *   The full file name of the executable.
 *  command char *   The name to give the command that invokes 'file'.
 * Output:
 *  return   int     0 - OK.
 *                   1 - Error.
 */


/*.......................................................................
 * Run a PGPLOT program on a VAX VMS machine in the background, with
 * sys$input redirected from NL: so that the child process does not
 * get sent its parent's signals.
 * Unfortunately system() can't be used. For some unknown reason
 *   system("spawn/nowait/sys$input=nl: command_line")
 * doesn't appear to do anything. It doesn't even produce an error
 * message to say why. If the nowait qualifier is removed it works fine,
 * but that is not what is wanted.
 *
 * Input:
 *  command    char *  The command line.
 * Output:
 *  return      int    0 - No error detected.
 *                     1 - Definate error detected.
 */


/*.......................................................................
 * Output a formatted /xw driver error message
 *
 * Input:
 *  char *buff   The error message.
 * Output:
 *  None.
 */


/* The xerrorhandler routine handles an X error.  All it does is set the */
/* xerror flag to true, reset fd_dispopen. , and print an error message. */


/* Sam Southard, Jr. */
/* Created: 12-Nov-1990 */
/* 16-Nov-1990	SNS/CIT	Now takes a buffer of shorts (instead of chars). */
/* 13-Sep-1991	SNS/CIT	Now uses "global" display, window, and incratom */
/* 23-Sep-1992	SNS/CIT	Now converts the buffer to network order as needed. */


/* Sam Southard, Jr. */
/* Created: 20-Nov-1990 */
/* 13-Sep-1991	SNS/CIT	Now uses static display and window */
/*  6-Nov-1994  MCS/TJP Change uninitialized pointer to 0 */


/* Sam Southard, Jr. */
/* Created: 13-Sep-1991 */
/* Modification History: */
/* 14-Feb-1992	SNS/CIT	Now includes support for multiple devices */


/* Sam Southard, Jr. */
/* Created: 20-Sep-1991 */


/* Sam Southard, Jr. */
/* Created: 23-Sep-1992 */


/* If one were to port this driver to a new image format, then this is the
 * only routine that would need to be rewritten.
 */


/*
  Begins a new plot page. Allocates memory for the pixmap, which
  should be freed after the page has been written to file
*/


/*
  Called when page is done. Should write file and free
  memory allocated in start_plot() for pixmap.
*/


/*
  Used first time through PNDRIV()
*/


/* set a single pixel's color */


/*.......................................................................
 * Allocate and return an initialized Image container object.
 * This function creates two PGPLOT widgets. One will be used to display
 * a gray-scale image. The other will be used to display a slice through
 * the image.
 *
 * Note that the widgets are not opened to PGPLOT and nothing
 * will be displayed until display_fn() is first
 * called. These operations must be postponed until after the widgets have
 * been realized.
 *
 * Input:
 *  image_size unsigned    The number of pixels along each side of the
 *                         square image array. This must be an odd
 *                         number (so that there can be a central pixel).
 *  slice_size unsigned    The dimension of the slice array (>=2).
 *  fn         IMAGE_FN(*) The initial display function.
 *  parent       Widget    The widget in which to create the PGPLOT widgets.
 *  w_top        Widget    The top-level widget of the application.
 * Output:
 *  return   Image *  The new image container, or NULL on error.
 */


/*.......................................................................
 * Delete an Image container previously returned by new_Image().
 *
 * Input:
 *  im        Image *  The container to be deleted (or NULL).
 * Output:
 *  return    Image *  The deleted container (always NULL).
 */


/*.......................................................................
 * Display a new function in the image window.
 *
 * Input:
 *  im    Image *   The image context object.
 *  fn IMAGE_FN(*)  The function to be displayed.
 */


/*.......................................................................
 * Display the current image function in a specified PGPLOT device.
 *
 *
 * Input:
 *  im    Image *   The image context object.
 *  id      int     The id of the PGPLOT device to display.
 */


/*.......................................................................
 * Display a new slice in the slice window.
 *
 * Input:
 *  im    Image *   The image context object.
 *  va   Vertex *   The vertex of one end of the slice line.
 *  vb   Vertex *   The vertex of the opposite end of the slice line.
 */


/*.......................................................................
 * Display usage instructions in the slice window.
 *
 * Input:
 *  im     Image *   The image object.
 */


/*.......................................................................
 * Create an option menu.
 *
 * Input:
 *  name             char *  The name of the menu.
 *  label            char *  The instructive label to place to the left of
 *                           the option menu.
 *  parent         Widget    The widget in which to place the option menu.
 *  nopt              int    The number of option fields.
 *  opts         MenuItem *  An array of nopt option fields.
 *  client_data XtPointer    The client_data argument to be passed to each
 *                           callback function.
 * Output:
 *  return      Widget    The menu, or NULL on error.
 */


/*.......................................................................
 * This callback is called when the user selects the start position
 * of a slice line.
 *
 * Input:
 *  Widget          widget The PGPLOT widget that had a cursor event.
 *  client_data  XtPointer The optional client data pointer passed to
 *                         xap_arm_cursor().
 *  call_data    XtPointer The pointer to the context of the event
 *                         as a (XapCursorCallbackStruct *) cast to
 *                         (XtPointer).
 */


/*.......................................................................
 * This callback is called when the user selects the end position
 * of a slice line.
 *
 * Input:
 *  Widget          widget The PGPLOT widget that had a cursor event.
 *  client_data  XtPointer The optional client data pointer passed to
 *                         xap_arm_cursor().
 *  call_data    XtPointer The pointer to the context of the event
 *                         as a (XapCursorCallbackStruct *) cast to
 *                         (XtPointer).
 */


/*.......................................................................
 * Create the menu bar of the application.
 *
 * Input:
 *  im        Image * The image object of the application.
 *  w_main   Widget   The form widget for the menubar
 */


/*.......................................................................
 * Create a popup prompt-dialog with a specified prompt and initial value.
 *
 * Input:
 *  w             Widget    The widget of the button that invoked the dialog.
 *  name            char *  The name to give the popup. Note that
 *                          XaCreatePromptDialog() appends _prompt to this.
 *  prompt          char *  The dialog prompt string.
 *  value           char *  The initial value to display, or NULL.
 *  ok_fn XtCallbackProc    The callback function for the OK button.
 *  ok_data    XtPointer    The callback client_data argument.
 * Output:
 *  return  Widget     The dialog widget.
 */


/*.......................................................................
 * This is a motion-event callback for the image window. It reports the
 * current position of the cursor in world coordinates.
 *
 * Input:
 *  w           Widget   The im->w_image PGPLOT widget.
 *  context  XtPointer   The im->w_coord label widget cast to XtPointer.
 *  event       XEvent * The motion event.
 *  call_next  Boolean * *call_next will be left as True so that any
 *                       following event handlers will get called.
 */


/*.......................................................................
 * Change the colors used to display the current image.
 *
 * Inputs:
 *  im     Image *  The image widget resource object.
 *  lev    float *  The array of n normalized brightness levels at which
 *                  red,green and blue levels are to be defined.
 *  r      float *  The red brightness at each of the levels in lev[].
 *  g      float *  The green brightness at each of the levels in lev[].
 *  b      float *  The blue brightness at each of the levels in lev[].
 *  n        int    The number of values in each of lev[],r[],g[] and b[].
 */


/*.......................................................................
 * This is called once to initialize the PGPLOT part of the widget class
 * structure when the first widget instance of this type is created.
 *
 * Input:
 *  w   WidgetClass   The class record to be initialized.
 */


/*.......................................................................
 * This is called to check resource derived defaults and initialize
 * a PGPLOT widget instance.
 *
 * Input:
 *  request    Widget   The instance widget type with the resource values
 *                      requested by the client.
 *  new_w      Widget   The resulting instance widget with allowed
 *                      resource values.
 *  args      ArgList   The widget-creation argument list used to override
 *                      default values.
 *  num_args Cardinal   The number of arguments in args.
 */


/*.......................................................................
 * Create and clear the window of a PGPLOT widget instance.
 *
 * Input:
 *  widget             Widget   The widget to be realized.
 *  mask          XtValueMask * The bit-mask that specifies which
 *                              attributes have been set in 'attr'.
 *  attr XSetWindowAttributes * The container of the pre-set window
 *                              attributes specified in 'mask'.
 */


/*.......................................................................
 * PGPLOT Widget destructor function.
 *
 * Input:
 *  widget    Widget   The widget whose resources are to be released.
 */


/*.......................................................................
 * PGPLOT Widget resize function.
 *
 * Input:
 *  widget    Widget   The widget that is being resized.
 */


/*.......................................................................
 * The expose-event handler for PGPLOT widgets.
 *
 * Input:
 *  widget   Widget   The widget that is to be re-drawn.
 *  event    XEvent   The expose event that invoked the callback.
 *  region   Region   The area to be re-drawn.
 */


/*.......................................................................
 * This function is called whenever one or more resource values are
 * changed, to give the widget a chance to re-configure itself to
 * reflect the new values.
 *
 * Input:
 *  old_widget Widget   A copy of the widget before the change was made.
 *  req_widget Widget   The same as new_w but with the resources evaluated
 *                      by the superclasses.
 *  new_widget Widget   The widget with the new values in place. This
 *                      is also the output widget so changes made to
 *                      this widget will be in the final widget.
 *  args      ArgList   The resource argument list responsible for the
 *                      changes.
 *  num_args Cardinal * The number of arguments in args.
 * Output:
 *  return    Boolean   Return True if the widget needs to be re-displayed,
 *                      or False if not.
 */


/*.......................................................................
 * Whenever the parent widget wishes to resize a PGPLOT widget, this
 * function is called to give the widget a chance to veto or otherwise
 * modify the requested new geometry.
 *
 * Input:
 *  widget             Widget   The widget wrt which the geometry change
 *                              pertains.
 *  request  XtWidgetGeometry * The requested widget geometry.
 * Input/Output:
 *  reply    XtWidgetGeometry * The returned allowed widget geometry.
 * Output:
 *  return   XtGeometryResult   Return status from:
 *                               XtGeometryYes
 *                                 The requested geometry is acceptible.
 *                               XtGeometryAlmost
 *                                 An acceptible revision of the requested
 *                                 geometry has been encoded in *reply.
 *                               XtGeometryNo
 *                                 The requested geometry is identical
 *                                 to the existing geometry.
 */


/*.......................................................................
 * Find an inactive PGPLOT widget of a given name, open it to PGPLOT,
 * and move it to the head of the active list of widgets.
 *
 * Input:
 *  name         char *  The name of the widget to be opened.
 * Output:
 *  w  XaPgplotWidget    The selected widget, or NULL on error.
 */


/*.......................................................................
 * Find an active PGPLOT widget of a given name, close it to PGPLOT and
 * move it to the head of the inactive list of widgets.
 *
 * Input:
 *  name             char *  The name of the widget.
 * Output:
 *  return XaPgplotWidget    The selected widget, or NULL if not found.
 */


/*.......................................................................
 * Lookup a widget by name from a given list of widgets.
 *
 * Input:
 *  name             char * The name of the widget.
 *  type              int   The enumerated name of the list to search,
 *                          from:
 *                            XAP_ACTIVE_WIDGETS
 *                            XAP_FREE_WIDGETS
 * Output:
 *  prev   XaPgplotWidget * *prev will either be NULL if the widget
 *                          was at the head of the list, or be the
 *                          widget in the list that immediately precedes
 *                          the specified widget.
 *  return XaPgplotWidget   The located widget, or NULL if not found.
 */


/*.......................................................................
 * Lookup a widget by its PGPLOT id from a given list of widgets.
 *
 * Input:
 *  xaslct_id         int   The number used by PGPLOT to select the
 *                          device.
 *  type              int   The enumerated name of the list to search,
 *                          from:
 *                            XAP_ACTIVE_WIDGETS
 *                            XAP_FREE_WIDGETS
 * Output:
 *  prev   XaPgplotWidget * *prev will either be NULL if the widget
 *                          was at the head of the list, or be the
 *                          widget in the list that immediately precedes
 *                          the specified widget.
 *  return XaPgplotWidget   The located widget, or NULL if not found.
 */


/*.......................................................................
 * Lookup one of the PGPLOT class widget lists by its enumerated type.
 *
 * Input:
 *  type            int   The enumerated name of the list, from:
 *                          XAP_ACTIVE_WIDGETS
 *                          XAP_FREE_WIDGETS
 * Output:
 *  return XaPgplotList * The widget list, or NULL if not recognized.
 */


/*.......................................................................
 * Remove a given widget from one of the PGPLOT class widget lists.
 *
 * Input:
 *  name             char * The name of the widget to be removed from
 *                          the list.
 *  type              int   The enumerated name of the list from which to
 *                          remove the widget, from:
 *                            XAP_ACTIVE_WIDGETS
 *                            XAP_FREE_WIDGETS
 * Output:
 *  return XaPgplotWidget   The removed widget, or NULL if not found.
 */


/*.......................................................................
 * Prepend a PGPLOT widget to a given PGPLOT class widget list.
 *
 * Input:
 *  w      XaPgplotWidget   The widget to add to the list.
 *  type              int   The enumerated name of the list to add to,
 *                          from:
 *                            XAP_ACTIVE_WIDGETS
 *                            XAP_FREE_WIDGETS
 * Output:
 *  return XaPgplotWidget   The added widget (the same as w), or NULL
 *                          on error.
 */


/*.......................................................................
 * Return the currently selected PGPLOT device.
 *
 * Input:
 *  context           char * If no XaPgplot device is currently selected
 *                           and context!=NULL then, an error message of
 *                           the form printf("%s: ...\n", context) will
 *                           be written to stderr reporting that no
 *                           device is open.
 * Output:
 *  return  XaPgplotWidget   The currently selected PGPLOT device, or
 *                           NULL if no device is currently selected.
 */


/*.......................................................................
 * This function is called upon by the pgxwin toolkit whenever the
 * pixmap used as backing store needs to be resized.
 *
 * Input:
 *  pgx      PgxWin *   The pgxwin toolkit context descriptor.
 *  width  unsigned     The desired new pixmap width.
 *  height unsigned     The desired new pixmap height.
 */


/*.......................................................................
 * This function provides an asynchronous alternative to pgband() and
 * pgcurs(). It creates an event handler which ensures that the X cursor
 * is augmented with selected rubber-band graphics when visible, and
 * which calls a specified user cursor-input callback when the user
 * presses a key or button over the window. As with pgband() all
 * specified and reported coordinates are world coordinates. The
 * cursor is automatically disarmed in xadriv() if the pgband() opcode
 * is invoked. It is also disarmed when the pgplot close-workstation
 * opcode is invoked.
 *
 * Input:
 *  widget       Widget   The PGPLOT widget to connect a cursor to.
 *  mode            int   The type of cursor augmentation (see XaPgplot.h).
 *  xref,yref     float   The world-coordinate reference point for band-type
 *                        cursors.
 *  callback XtCallbackProc The callback function to call when input events
 *                        are received.
 *  client_data    void * Client-specific data to be sent to the callback
 *                        function.
 * Output:
 *  return          int   0 - OK.
 *                        1 - Error.
 */


/*.......................................................................
 * Erase the cursor, remove input callbacks and remove the cursor
 * event handler.
 *
 * Input:
 *  widget     Widget   The PGPLOT widget to disconnect the cursor from.
 * Output:
 *  return        int   0 - OK.
 *                      1 - Error.
 */


/*.......................................................................
 * This is the cursor event handler registered by xap_arm_cursor().
 */


/*.......................................................................
 * The private work-horse function of xap_arm_cursor(). Note that
 * this function takes an XaPgplotWidget argument whereas xap_arm_cursor()
 * takes a generic Widget argument.
 *
 * Input:
 *  w    XaPgplotWidget   The PGPLOT widget to connect a cursor to.
 *  mode            int   The type of cursor augmentation (see XaPgplot.h).
 *  xref,yref     float   The world-coordinate reference point for band-type
 *                        cursors.
 *  callback XtCallbackProc The callback function to call when input events
 *                        are received, or 0 if keyboard and button
 *                        events are to be handled externally.
 *  client_data    void * Client-specific data to be sent to the callback
 *                        function.
 * Output:
 *  return          int   0 - OK.
 *                        1 - Error.
 */


/*.......................................................................
 * The private work-horse function of xap_disarm_cursor(). Note that
 * this function takes an XaPgplotWidget argument whereas
 * xap_disarm_cursor() takes a generic Widget argument.
 *
 *  w  XaPgplotWidget   The widget to disconnect the cursor from.
 * Output:
 *  return        int   0 - OK.
 *                      1 - Error.
 */


/*.......................................................................
 * Get the visual and colormap for a new window as specified by X
 * resource values.
 *
 * Input:
 *  w    XaPgplotWidget   The PGPLOT widget.
 * Output:
 *  return          int   0 - OK.
 *                        1 - Error.
 */


/*.......................................................................
 * Return an unambiguous PGPLOT device-specification that can be used
 * as the FILE argument of cpgbeg() to open a given PGPLOT widget.
 *
 * Input:
 *  widget  Widget   The PGPLOT widget to return a device string for.
 * Output:
 *  return    char * The PGPLOT device-specication. Note that the returned
 *                   string is owned by the widget driver and must not be
 *                   free()d or overwritten.
 */


/*.......................................................................
 * Return the pgslct_id of the given widget. This can then be used with
 * the cpgslct() function to select the widget as the currently
 * active widget.
 *
 * Input:
 *  widget  Widget   The PGPLOT widget to return a device string for.
 * Output:
 *  return     int   The PGPLOT device-id. This will be 0 if the widget
 *                   is not currently open to PGPLOT.
 */


/*.......................................................................
 * The following is a convenience none-variadic function for creating
 * a PGPLOT widget. Note that XtManageChild() should be applied to the
 * returned widget.
 *
 * Input:
 *  parent     Widget    The parent widget to adopt.
 *  name         char *  The name to give the widget.
 *  arglist   ArgList    A list of X resources.
 *  argcount Cardinal    The number of X resources.
 * Output:
 *  return     Widget    The new PGPLOT widget.
 */


/*.......................................................................
 * Update the clip-area of the window to prevent pgxwin functions from
 * drawing over the highlight-borders.
 *
 * Input:
 *  w     XaPgplotWidget   The pgplot widget instance.
 */


/*.......................................................................
 * This function is a XtResourceDefaultProc function used to return
 * the default background color. It is used to initialize the
 * XtNbackground resource.
 */


/*.......................................................................
 * This function is a XtResourceDefaultProc function used to return
 * the default foreground color. It is used to initialize the
 * XtNforeground resource.
 */


/*.......................................................................
 * This is an application-level utility function for converting from
 * PGPLOT world coordinates to X-window pixel coordinates.
 *
 * Input:
 *  widget  Widget    The PGPLOT widget whose coordinates are to be
 *                    converted.
 *  wx, wy   float    The PGPLOT world coordinates to be converted.
 * Output:
 *  px, py     int *  On output, *px and *py will be assigned with the
 *                    X-window pixel coordinates that correspond to wx,wy.
 *  return     int    0 - OK.
 *                    1 - Error.
 */


/*.......................................................................
 * This is an application-level utility function for converting from
 * X-window pixel coordinates to PGPLOT world coordinates.
 *
 * Input:
 *  widget  Widget    The PGPLOT widget whose coordinates are to be
 *                    converted.
 *  px, py     int *  The X-window pixel coordinates to be converted.
 * Output:
 *  wx, wy   float *  On output, *wx and *wy will be assigned with the
 *                    PGPLOT world coordinates that correspond to px,py.
 *  return     int    0 - OK.
 *                    1 - Error.
 */


/*.......................................................................
 * This is an internal function for converting from X-window pixel
 * coordinates to PGPLOT world coordinates.
 *
 * Input:
 *  w  XaPgplotWidget   The widget whose coordinates are to be converted.
 *  px, py        int * The X-window pixel coordinates to be converted.
 * Output:
 *  wx, wy      float * On output, *wx and *wy will be assigned with the
 *                      PGPLOT world coordinates that correspond to px,py.
 *  return        int    0 - OK.
 *                       1 - Error.
 */


/*.......................................................................
 * This is an internal function for converting from PGPLOT world
 * coordinates to X-window pixel coordinates.
 *
 * Input:
 *  w  XaPgplotWidget   The widget whose coordinates are to be converted.
 *  wx, wy      float   The PGPLOT world coordinates to be converted.
 * Output:
 *  px, py       int *  On output, *px and *py will be assigned with the
 *                      X-window pixel coordinates that correspond to wx,wy.
 *  return        int   0 - OK.
 *                      1 - Error.
 */


/*.......................................................................
 * Create a pulldown menu.
 *
 * Input:
 *  name             char *  The name of the menu.
 *  label            char *  The label for the menubar button.
 *  parent         Widget    The widget in which to place the pulldown menu.
 *  nfield            int    The number of menu fields.
 *  fields       MenuItem *  An array of nfield menu fields.
 *  client_data XtPointer    The client_data argument to be passed to each
 *                           callback function.
 * Output:
 *  return         Widget    The cascade button of the menu, or NULL on error.
 */


/*.......................................................................
 * This callback is called when the user selects the start position
 * of a slice line.
 *
 * Input:
 *  Widget          widget The PGPLOT widget that had a cursor event.
 *  client_data  XtPointer The optional client data pointer passed to
 *                         xmp_arm_cursor().
 *  call_data    XtPointer The pointer to the context of the event
 *                         as a (XmpCursorCallbackStruct *) cast to
 *                         (XtPointer).
 */


/*.......................................................................
 * This callback is called when the user selects the end position
 * of a slice line.
 *
 * Input:
 *  Widget          widget The PGPLOT widget that had a cursor event.
 *  client_data  XtPointer The optional client data pointer passed to
 *                         xmp_arm_cursor().
 *  call_data    XtPointer The pointer to the context of the event
 *                         as a (XmpCursorCallbackStruct *) cast to
 *                         (XtPointer).
 */


/*.......................................................................
 * Create the menu bar of the application.
 *
 * Input:
 *  im        Image * The image object of the application.
 *  w_main   Widget   The main widget of the application.
 * Output:
 *  return   Widget   The menu-bar widget or NULL on error.
 */


/*.......................................................................
 * Create a popup prompt-dialog with a specified prompt and initial value.
 *
 * Input:
 *  w             Widget    The widget of the button that invoked the dialog.
 *  name            char *  The name to give the popup. Note that
 *                          XmCreatePromptDialog() appends _prompt to this.
 *  prompt          char *  The dialog prompt string.
 *  value           char *  The initial value to display, or NULL.
 *  ok_fn XtCallbackProc    The callback function for the OK button.
 *  ok_data    XtPointer    The callback client_data argument.
 * Output:
 *  return  Widget     The dialog widget.
 */


/*.......................................................................
 * Find an inactive PGPLOT widget of a given name, open it to PGPLOT,
 * and move it to the head of the active list of widgets.
 *
 * Input:
 *  name         char *  The name of the widget to be opened.
 * Output:
 *  w  XmPgplotWidget    The selected widget, or NULL on error.
 */


/*.......................................................................
 * Find an active PGPLOT widget of a given name, close it to PGPLOT and
 * move it to the head of the inactive list of widgets.
 *
 * Input:
 *  name             char *  The name of the widget.
 * Output:
 *  return XmPgplotWidget    The selected widget, or NULL if not found.
 */


/*.......................................................................
 * Lookup a widget by name from a given list of widgets.
 *
 * Input:
 *  name             char * The name of the widget.
 *  type              int   The enumerated name of the list to search,
 *                          from:
 *                            XMP_ACTIVE_WIDGETS
 *                            XMP_FREE_WIDGETS
 * Output:
 *  prev   XmPgplotWidget * *prev will either be NULL if the widget
 *                          was at the head of the list, or be the
 *                          widget in the list that immediately precedes
 *                          the specified widget.
 *  return XmPgplotWidget   The located widget, or NULL if not found.
 */


/*.......................................................................
 * Lookup a widget by its PGPLOT id from a given list of widgets.
 *
 * Input:
 *  xmslct_id         int   The number used by PGPLOT to select the
 *                          device.
 *  type              int   The enumerated name of the list to search,
 *                          from:
 *                            XMP_ACTIVE_WIDGETS
 *                            XMP_FREE_WIDGETS
 * Output:
 *  prev   XmPgplotWidget * *prev will either be NULL if the widget
 *                          was at the head of the list, or be the
 *                          widget in the list that immediately precedes
 *                          the specified widget.
 *  return XmPgplotWidget   The located widget, or NULL if not found.
 */


/*.......................................................................
 * Lookup one of the PGPLOT class widget lists by its enumerated type.
 *
 * Input:
 *  type            int   The enumerated name of the list, from:
 *                          XMP_ACTIVE_WIDGETS
 *                          XMP_FREE_WIDGETS
 * Output:
 *  return XmPgplotList * The widget list, or NULL if not recognized.
 */


/*.......................................................................
 * Remove a given widget from one of the PGPLOT class widget lists.
 *
 * Input:
 *  name             char * The name of the widget to be removed from
 *                          the list.
 *  type              int   The enumerated name of the list from which to
 *                          remove the widget, from:
 *                            XMP_ACTIVE_WIDGETS
 *                            XMP_FREE_WIDGETS
 * Output:
 *  return XmPgplotWidget   The removed widget, or NULL if not found.
 */


/*.......................................................................
 * Prepend a PGPLOT widget to a given PGPLOT class widget list.
 *
 * Input:
 *  w      XmPgplotWidget   The widget to add to the list.
 *  type              int   The enumerated name of the list to add to,
 *                          from:
 *                            XMP_ACTIVE_WIDGETS
 *                            XMP_FREE_WIDGETS
 * Output:
 *  return XmPgplotWidget   The added widget (the same as w), or NULL
 *                          on error.
 */


/*.......................................................................
 * Return the currently selected PGPLOT device.
 *
 * Input:
 *  context           char * If no XmPgplot device is currently selected
 *                           and context!=NULL then, an error message of
 *                           the form printf("%s: ...\n", context) will
 *                           be written to stderr reporting that no
 *                           device is open.
 * Output:
 *  return  XmPgplotWidget   The currently selected PGPLOT device, or
 *                           NULL if no device is currently selected.
 */


/*.......................................................................
 * Whenever the size of a pixmap and/or window of a PGPLOT winget are
 * changed, this function should be called to adjust scroll bars if the
 * parent is a scrolled window widget.
 *
 * Input:
 *  w     XmPgplotWidget   The pgplot widget instance.
 */


/*.......................................................................
 * This function is called whenever a scrollbar of a parent scrolled
 * window widget is moved.
 */


/*.......................................................................
 * This function provides an asynchronous alternative to pgband() and
 * pgcurs(). It creates an event handler which ensures that the X cursor
 * is augmented with selected rubber-band graphics when visible, and
 * which calls a specified user cursor-input callback when the user
 * presses a key or button over the window. As with pgband() all
 * specified and reported coordinates are world coordinates. The
 * cursor is automatically disarmed in xmdriv() if the pgband() opcode
 * is invoked. It is also disarmed when the pgplot close-workstation
 * opcode is invoked.
 *
 * Input:
 *  widget       Widget   The PGPLOT widget to connect a cursor to.
 *  mode            int   The type of cursor augmentation (see XmPgplot.h).
 *  xref,yref     float   The world-coordinate reference point for band-type
 *                        cursors.
 *  callback XtCallbackProc The callback function to call when input events
 *                        are received.
 *  client_data    void * Client-specific data to be sent to the callback
 *                        function.
 * Output:
 *  return          int   0 - OK.
 *                        1 - Error.
 */


/*.......................................................................
 * This is the cursor event handler registered by xmp_arm_cursor().
 */


/*.......................................................................
 * The private work-horse function of xmp_arm_cursor(). Note that
 * this function takes an XmPgplotWidget argument whereas xmp_arm_cursor()
 * takes a generic Widget argument.
 *
 * Input:
 *  w    XmPgplotWidget   The PGPLOT widget to connect a cursor to.
 *  mode            int   The type of cursor augmentation (see XmPgplot.h).
 *  xref,yref     float   The world-coordinate reference point for band-type
 *                        cursors.
 *  callback XtCallbackProc The callback function to call when input events
 *                        are received, or 0 if keyboard and button
 *                        events are to be handled externally.
 *  client_data    void * Client-specific data to be sent to the callback
 *                        function.
 * Output:
 *  return          int   0 - OK.
 *                        1 - Error.
 */


/*.......................................................................
 * The private work-horse function of xmp_disarm_cursor(). Note that
 * this function takes an XmPgplotWidget argument whereas
 * xmp_disarm_cursor() takes a generic Widget argument.
 *
 *  w  XmPgplotWidget   The widget to disconnect the cursor from.
 * Output:
 *  return        int   0 - OK.
 *                      1 - Error.
 */


/*.......................................................................
 * Get the visual and colormap for a new window as specified by X
 * resource values.
 *
 * Input:
 *  w    XmPgplotWidget   The PGPLOT widget.
 * Output:
 *  return          int   0 - OK.
 *                        1 - Error.
 */


/*.......................................................................
 * The following is a convenience none-variadic function for creating
 * a PGPLOT widget with scroll-bars. Note that XtManageChild() should
 * be applied to the returned widget if you want the PGPLOT window to
 * fit exactly within the ScrollBar widget area.
 *
 * Input:
 *  parent     Widget    The parent widget to adopt.
 *  name         char *  The name to give the widget.
 *  arglist   ArgList    A list of X resources.
 *  argcount Cardinal    The number of X resources.
 * Output:
 *  return     Widget    The new PGPLOT widget.
 */


/*.......................................................................
 * This is the callback used to destroy the ScrollBar parent of a widget.
 */


/*.......................................................................
 * Update the clip-area of the window to prevent pgxwin functions from
 * drawing over the highlight-borders.
 *
 * Input:
 *  w     XmPgplotWidget   The pgplot widget instance.
 */


/*.......................................................................
 * This function is a XtResourceDefaultProc function used to return
 * the default highlight color. It is used to initialize the
 * XmNhighlightColor resource.
 */


/*.......................................................................
 * This function is a XtResourceDefaultProc function used to return
 * the default background color. It is used to initialize the
 * XmNbackground resource.
 */


/*.......................................................................
 * This function is a XtResourceDefaultProc function used to return
 * the default foreground color. It is used to initialize the
 * XmNforeground resource.
 */


/*.......................................................................
 * This is an internal function for converting from X-window pixel
 * coordinates to PGPLOT world coordinates.
 *
 * Input:
 *  w  XmPgplotWidget   The widget whose coordinates are to be converted.
 *  px, py        int * The X-window pixel coordinates to be converted.
 * Output:
 *  wx, wy      float * On output, *wx and *wy will be assigned with the
 *                      PGPLOT world coordinates that correspond to px,py.
 *  return        int    0 - OK.
 *                       1 - Error.
 */


/*.......................................................................
 * This is an internal function for converting from PGPLOT world
 * coordinates to X-window pixel coordinates.
 *
 * Input:
 *  w  XmPgplotWidget   The widget whose coordinates are to be converted.
 *  wx, wy      float   The PGPLOT world coordinates to be converted.
 * Output:
 *  px, py       int *  On output, *px and *py will be assigned with the
 *                      X-window pixel coordinates that correspond to wx,wy.
 *  return        int   0 - OK.
 *                      1 - Error.
 */


/*.......................................................................
 * This function provides the TCL command that creates a PGPLOT widget.
 *
 * Input:
 *  context   ClientData    The client_data argument specified in
 *                          TkPgplot_Init() when PgplotCmd was registered.
 *                          This is the main window cast to (ClientData).
 *  interp    Tcl_Interp *  The TCL intrepreter.
 *  argc             int    The number of command arguments.
 *  argv            char ** The array of 'argc' command arguments.
 *                          argv[0] = "pgplot"
 *                          argv[1] = the name to give the new widget.
 *                          argv[2..argc-1] = attribute settings.
 * Output:
 *  return           int    TCL_OK    - Success.
 *                          TCL_ERROR - Failure.
 */


/*.......................................................................
 * Create a new widget instance object.
 *
 * Input:
 *  interp   Tcl_Interp *  The TCL interpreter object.
 *  main_w    Tk_Window    The main window of the application.
 *  name           char *  The name to give the new widget.
 *  argc            int    The number of argument in argv[]
 *  argv           char ** Any configuration arguments.
 * Output:
 *  return     TkPgplot *  The new PGPLOT widget, or NULL on error.
 *                         If NULL is returned then the context of the
 *                         error will have been recorded in the result
 *                         field of the interpreter.
 */


/*.......................................................................
 * Delete a TkPgplot widget.
 *
 * Input:
 *  tkpg    TkPgplot *   The widget to be deleted.
 * Output:
 *  return  TkPgplot *   Always NULL.
 */


/*.......................................................................
 * Whenever the size of a pixmap and/or window of a PGPLOT winget are
 * changed, this function should be called to adjust scroll bars.
 *
 * Input:
 *  tkpg     TkPgplot *  The pgplot widget instance.
 */


/*.......................................................................
 * Update the clip-area of the window to prevent pgxwin functions from
 * drawing over the highlight-borders.
 *
 * Input:
 *  tkpg    TkPgplot *  The pgplot widget instance.
 */


/*.......................................................................
 * Find an inactive PGPLOT widget of a given name, open it to PGPLOT,
 * and move it to the head of the active list of widgets.
 *
 * Input:
 *  name         char *  The name of the widget to be opened.
 * Output:
 *  tkpg     TkPgplot *  The selected widget, or NULL on error.
 */


/*.......................................................................
 * Find an active PGPLOT widget of a given name, close it to PGPLOT and
 * move it to the head of the inactive list of widgets.
 *
 * Input:
 *  name       char *  The name of the widget.
 * Output:
 *  return TkPgplot *  The selected widget, or NULL if not found.
 */


/*.......................................................................
 * Lookup a widget by name from a given list of widgets.
 *
 * Input:
 *  name       char *  The name of the widget.
 *  type        int    The enumerated name of the list to search,
 *                     from:
 *                       TKPG_ACTIVE_WIDGETS
 *                       TKPG_FREE_WIDGETS
 * Output:
 *  prev   TkPgplot ** *prev will either be NULL if the widget
 *                     was at the head of the list, or be the
 *                     widget in the list that immediately precedes
 *                     the specified widget.
 *  return TkPgplot *  The located widget, or NULL if not found.
 */


/*.......................................................................
 * Lookup a widget by its PGPLOT id from a given list of widgets.
 *
 * Input:
 *  tkslct_id   int    The number used by PGPLOT to select the
 *                     device.
 *  type        int    The enumerated name of the list to search,
 *                     from:
 *                       TKPG_ACTIVE_WIDGETS
 *                       TKPG_FREE_WIDGETS
 * Output:
 *  prev   TkPgplot ** *prev will either be NULL if the widget
 *                     was at the head of the list, or be the
 *                     widget in the list that immediately precedes
 *                     the specified widget.
 *  return TkPgplot *  The located widget, or NULL if not found.
 */


/*.......................................................................
 * Lookup one of the PGPLOT class widget lists by its enumerated type.
 *
 * Input:
 *  type            int   The enumerated name of the list, from:
 *                          TKPG_ACTIVE_WIDGETS
 *                          TKPG_FREE_WIDGETS
 * Output:
 *  return TkPgplotList * The widget list, or NULL if not recognized.
 */


/*.......................................................................
 * Remove a given widget from one of the PGPLOT class widget lists.
 *
 * Input:
 *  name       char *  The name of the widget to be removed from
 *                     the list.
 *  type        int    The enumerated name of the list from which to
 *                     remove the widget, from:
 *                       TKPG_ACTIVE_WIDGETS
 *                       TKPG_FREE_WIDGETS
 * Output:
 *  return TkPgplot *  The removed widget, or NULL if not found.
 */


/*.......................................................................
 * Prepend a PGPLOT widget to a given PGPLOT class widget list.
 *
 * Input:
 *  tkpg   TkPgplot *  The widget to add to the list.
 *  type        int    The enumerated name of the list to add to, from:
 *                       TKPG_ACTIVE_WIDGETS
 *                       TKPG_FREE_WIDGETS
 * Output:
 *  return TkPgplot *  The added widget (the same as tkpg), or NULL
 *                     on error.
 */


/*.......................................................................
 * Return the currently selected PGPLOT device.
 *
 * Input:
 *  context     char *  If no TkPgplot device is currently selected
 *                      and context!=NULL then, an error message of
 *                      the form printf("%s: ...\n", context) will
 *                      be written to stderr reporting that no
 *                      device is open.
 * Output:
 *  return  TkPgplot *  The currently selected PGPLOT device, or
 *                      NULL if no device is currently selected.
 */


/*.......................................................................
 * This function services TCL commands for a given widget.
 *
 * Input:
 *  context   ClientData    The tkpg widget cast to (ClientData).
 *  interp    Tcl_Interp *  The TCL intrepreter.
 *  argc             int    The number of command arguments.
 *  argv            char ** The array of 'argc' command arguments.
 * Output:
 *  return           int    TCL_OK    - Success.
 *                          TCL_ERROR - Failure.
 */


/*.......................................................................
 * This is a private cleanup-return function of tkpg_InstanceCommand().
 * It should be used to return from said function after Tk_Preserve() has
 * been called. It calls Tk_Release() on the widget to unblock deletion
 * and returns the specified error code.
 *
 * Input:
 *  context   ClientData    The tkpg widget cast to (ClientData).
 *  iret             int    TCL_OK or TCL_ERROR.
 * Output:
 *  return           int    The value of iret.
 */


/*.......................................................................
 * This function is services TCL commands for a given widget.
 *
 * Input:
 *  tkpg        TkPgplot *  The widget record to be configured.
 *  interp    Tcl_Interp *  The TCL intrepreter.
 *  argc             int    The number of configuration arguments.
 *  argv            char ** The array of 'argc' configuration arguments.
 *  flags            int    The flags argument of Tk_ConfigureWidget():
 *                           0                - No flags.
 *                           TK_CONFIG_ARGV   - Override the X defaults
 *                                              database and the configSpecs
 *                                              defaults.
 * Output:
 *  return           int    TCL_OK    - Success.
 *                          TCL_ERROR - Failure.
 */


/*.......................................................................
 * This is the main X event callback for Pgplot widgets.
 *
 * Input:
 *  context   ClientData    The tkpg widget cast to (ClientData).
 *  event         XEvent *  The event that triggered the callback.
 */


/*.......................................................................
 * The expose-event handler for PGPLOT widgets.
 *
 * Input:
 *  tkpg   TkPgplot * The Tk Pgplot widget.
 *  event    XEvent   The expose event that invoked the callback.
 */


/*.......................................................................
 * Re-draw the focus highlight border if it has a finite size.
 *
 * Input:
 *  tkpg    TkPgplot * The Tk Pgplot widget.
 */


/*.......................................................................
 * Re-draw the 3D border if necessary.
 *
 * Input:
 *  tkpg    TkPgplot * The Tk Pgplot widget.
 */


/*.......................................................................
 * Augment the cursor of a given widget.
 *
 * Input:
 *  tkpg       TkPgplot * The PGPLOT widget to connect a cursor to.
 *  mode TkpgCursorMode   The type of cursor augmentation.
 *  xref,yref     float   The world-coordinate reference point for band-type
 *                        cursors.
 *  ci              int   The color index with which to plot the cursor,
 *                        or -1 to select the current foreground color.
 * Output:
 *  return          int   TCL_OK or TCL_ERROR.
 */


/*.......................................................................
 * This is the X event callback for Pgplot cursor events. It is called
 * only when the cursor augmentation has been established by
 * tkpg_SetCursor() and not cleared by tkpg_ClrCursor().
 *
 * Input:
 *  context   ClientData    The tkpg widget cast to (ClientData).
 *  event         XEvent *  The event that triggered the callback.
 */


/*.......................................................................
 * Clear the cursor of a given widget.
 *
 *  tkpg  TkPgplot * The widget to disconnect the cursor from.
 */


/*.......................................................................
 * Augment the cursor as specified in the arguments of the setcursor
 * widget command.
 *
 * Input:
 *  tkpg        TkPgplot *  The widget record to be configured.
 *  interp    Tcl_Interp *  The TCL intrepreter.
 *  argc             int    The number of configuration arguments.
 *  argv            char ** The array of 'argc' configuration arguments.
 *                           [0] The type of cursor augmentation, from:
 *                                norm  - Un-augmented X cursor
 *                                line  - Line cursor between ref and pointer
 *                                rect  - Rectangle between ref and pointer
 *                                yrng  - Horizontal lines at ref.x & pointer.x
 *                                xrng  - Vertical lines at ref.y & pointer.y
 *                                hline - Horizontal line cursor at y=ref.y
 *                                vline - Vertical line cursor at x=ref.x
 *                                cross - Pointer centered cross-hair
 *                           [1] The X-axis world coordinate at which
 *                               to anchor rect,yrng and xrng cursors.
 *                           [2] The Y-axis world coordinate at which
 *                               to anchor rect,yrng and xrng cursors.
 *                           [3] The color index of the cursor.
 *  flags            int    The flags argument of Tk_ConfigureWidget():
 *                           0                - No flags.
 *                           TK_CONFIG_ARGV   - Override the X defaults
 *                                              database and the configSpecs
 *                                              defaults.
 * Output:
 *  return           int    TCL_OK    - Success.
 *                          TCL_ERROR - Failure.
 */


/*.......................................................................
 * Return an unambiguous PGPLOT device-specification that can be used
 * as the FILE argument of cpgbeg() to open a given Rivet PGPLOT widget.
 *
 * Input:
 *  widget Rivetobj   A rivet pgplot widget.
 * Output:
 *  return     char * The PGPLOT device-specication. Note that the returned
 *                    string is owned by the widget driver and must not be
 *                    free()d or overwritten.
 */


/*.......................................................................
 * Return the pgslct_id of the given Rivet pgplot widget. This can then
 * be used with the cpgslct() function to select the widget as the currently
 * active widget.
 *
 * Input:
 *  widget Rivetobj   A rivet pgplot widget.
 * Output:
 *  return     int   The PGPLOT device-id. This will be 0 if the widget
 *                   is not currently open to PGPLOT.
 */


/*.......................................................................
 * Convert from X window pixel coordinates to PGPLOT world coordinates.
 *
 * Input:
 *  widget Rivetobj    A rivet pgplot widget.
 *  px, py      int    The X-window pixel coordinates to be converted.
 *  wx, wy    float *  The corresponding PGPLOT world coordinates are
 *                     assigned to the variables pointed to by wx and wy.
 * Output:
 *  return      int    0 - OK.
 *                     1 - Error.
 */


/*.......................................................................
 * Convert from PGPLOT world coordinates to X window pixel coordinates.
 *
 * Input:
 *  widget Rivetobj    A rivet pgplot widget.
 *  wx, wy    float    The PGPLOT world coordinates to be converted.
 *  px, py      int *  The corresponding X-window pixel coordinates are
 *                     assigned to the variables pointed to by px and py.
 * Output:
 *  return      int    0 - OK.
 *                     1 - Error.
 */


/*.......................................................................
 * Refresh the contents of the window.
 *
 * Input:
 *  tkpg        TkPgplot *  The widget record to be configured.
 * Output:
 *  return           int    0 - OK.
 *                          1 - Error.
 */


/*.......................................................................
 * Whenever the color representation of the background color is changed
 * via PGPLOT, this function is called to update the Tk 3D border.
 *
 * Input:
 *  tkpg     TkPgplot *   The associated PGPLOT widget.
 */


/*.......................................................................
 * Respond to an xview or yview scrollbar command.
 *
 * Input:
 *  tkpg        TkPgplot *  The widget record to be configured.
 *  interp    Tcl_Interp *  The TCL intrepreter.
 *  widget          char *  The name of the PGPLOT widget.
 *  view            char *  "xview" or "yview".
 *  argc             int    The number of configuration arguments.
 *  argv            char ** The array of 'argc' configuration arguments.
 * Output:
 *  return           int    TCL_OK    - Success.
 *                          TCL_ERROR - Failure.
 */


/*.......................................................................
 * This is a private error-return function of tkpg_scrollbar_callback().
 *
 * Input:
 *  tkpg        TkPgplot *  The widget record.
 *  interp    Tcl_Interp *  The TCL intrepreter.
 *  widget          char *  The name of the PGPLOT widget.
 *  view            char *  "xview" or "yview".
 *  argc             int    The number of arguments in argv.
 *  argv            char ** The array of 'argc' configuration arguments.
 * Output:
 *  return           int    TCL_ERROR and the context of the error
 *                          is recorded in interp->result.
 */


/*.......................................................................
 * Implement the Tcl world function. This converts an X-window
 * pixel coordinate to the corresponding PGPLOT world coordinate.
 *
 * Input:
 *  tkpg        TkPgplot *  The widget record.
 *  interp    Tcl_Interp *  The TCL intrepreter.
 *  widget          char *  The name of the PGPLOT widget.
 *  argc             int    The number of configuration arguments.
 *  argv            char ** The array of 'argc' configuration arguments.
 *                           [0] The coordinate axes to convert, from:
 *                                "x"  - Convert an X-axis coord.
 *                                "y"  - Convert a Y-axis coord.
 *                                "xy" - Convert a an X Y axis pair.
 *                           [1] An X-axis pixel coordinate if [0][0] is
 *                               'x'.
 *                               A Y-axis pixel coordinate if [0][0] is
 *                               'y'.
 *                           [2] This is only expected if [0]=="xy". It
 *                               should then contain the Y-axis
 *                               coordinate to be converted.
 * Output:
 *  return           int    TCL_OK    - Success.
 *                          TCL_ERROR - Failure.
 */


/*.......................................................................
 * Implement the Tcl pixel function. This converts PGPLOT world
 * coordinates to X-window pixel coordinates.
 *
 * Input:
 *  tkpg        TkPgplot *  The widget record.
 *  interp    Tcl_Interp *  The TCL intrepreter.
 *  widget          char *  The name of the PGPLOT widget.
 *  argc             int    The number of configuration arguments.
 *  argv            char ** The array of 'argc' configuration arguments.
 *                           [0] The coordinate axes to convert, from:
 *                                "x"  - Convert an X-axis coord.
 *                                "y"  - Convert a Y-axis coord.
 *                                "xy" - Convert a an X Y axis pair.
 *                           [1] An X-axis world coordinate if [0][0] is
 *                               'x'.
 *                               A Y-axis world coordinate if [0][0] is
 *                               'y'.
 *                           [2] This is only expected if [0]=="xy". It
 *                               should then contain the Y-axis
 *                               coordinate to be converted.
 * Output:
 *  return           int    TCL_OK    - Success.
 *                          TCL_ERROR - Failure.
 */


/*.......................................................................
 * Implement the Tcl "return PGPLOT id" function.
 *
 * Input:
 *  tkpg        TkPgplot *  The widget record.
 *  interp    Tcl_Interp *  The TCL intrepreter.
 *  widget          char *  The name of the PGPLOT widget.
 *  argc             int    The number of configuration arguments.
 *  argv            char ** The array of 'argc' configuration arguments.
 *                          (None are expected).
 * Output:
 *  return           int    TCL_OK    - Success.
 *                          TCL_ERROR - Failure.
 */


/*.......................................................................
 * Implement the Tcl "return PGPLOT device specifier" function.
 *
 * Input:
 *  tkpg        TkPgplot *  The widget record.
 *  interp    Tcl_Interp *  The TCL intrepreter.
 *  widget          char *  The name of the PGPLOT widget.
 *  argc             int    The number of configuration arguments.
 *  argv            char ** The array of 'argc' configuration arguments.
 *                          (None are expected).
 * Output:
 *  return           int    TCL_OK    - Success.
 *                          TCL_ERROR - Failure.
 */


/*.......................................................................
 * Return the toplevel window ID of a given tk pathname.
 *
 * Input:
 *  interp  Tcl_Interp *  The TCL intrepreter.
 *  main_w   Tk_Window    The main window of the application.
 *  path          char *  The tk path name of a window.
 * Output:
 *  return   Tk_Window    The top-level window of the path, or NULL if
 *                        it doesn't exist. In the latter case an error
 *                        message will have been appended to interp->result.
 */


/*.......................................................................
 * This is the application initialization file that is called by Tk_Main().
 */


/*.......................................................................
 * This function provides the TCL command that creates a pgdemo
 * manipulation command. This opens the two given PGPLOT widgets to
 * PGPLOT, establishes a cursor handler and records the state of the
 * demo in a dynamically allocated container.
 *
 * Input:
 *  data      ClientData    The main window cast to ClientData.
 *  interp    Tcl_Interp *  The TCL intrepreter of the demo.
 *  argc             int    The number of command arguments.
 *  argv            char ** The array of 'argc' command arguments.
 *                          argv[0] = "create_pgdemo"
 *                          argv[1] = The name to give the new command.
 *                          argv[2] = The name of the image widget.
 *                          argv[3] = The name of the slice widget.
 * Output:
 *  return           int    TCL_OK    - Success.
 *                          TCL_ERROR - Failure.
 */


/*.......................................................................
 * Create a new PGPLOT demo instance command and its associated context
 * object.
 *
 * Input:
 *  interp   Tcl_Interp *  The TCL interpreter object.
 *  caller         char *  The name of the calling TCL command.
 *  cmd            char *  The name to give the new demo-instance command.
 *  image_device   char *  The PGPLOT device specification to use to open
 *                         the image-display device.
 *  slice_device   char *  The PGPLOT device specification to use to open
 *                         the slice-display device.
 * Output:
 *  return       Pgdemo *  The new demo object, or NULL on error.
 *                         If NULL is returned then the context of the
 *                         error will have been recorded in the result
 *                         field of the interpreter.
 */


/*.......................................................................
 * Delete the context of a Pgdemo instance command.
 *
 * Input:
 *  demo     Pgdemo *   The widget to be deleted.
 * Output:
 *  return  Pgdemo *   Always NULL.
 */


/*.......................................................................
 * This function implements a given Tcl PGPLOT demo instance command.
 *
 * Input:
 *  data      ClientData    The demo context object cast to (ClientData).
 *  interp    Tcl_Interp *  The TCL intrepreter.
 *  argc             int    The number of command arguments.
 *  argv            char ** The array of 'argc' command arguments.
 *                          argv[0] - the name of the demo command.
 *                          argv[1..] - One of:
 *                           save device_spec
 *                           function image_function
 *                           slice x1 y1 x2 y2
 * Output:
 *  return           int    TCL_OK    - Success.
 *                          TCL_ERROR - Failure.
 */


/*.......................................................................
 * Implement the demo "save" command. This takes a PGPLOT device
 * specification as its argument.
 *
 * Input:
 *  demo       Pgdemo *   The demo being serviced.
 *  interp Tcl_Interp *   The TCL interpreter of the demo.
 *  argc          int     The number of TCL arguments in argv[].
 *  argv         char **  An array of 'argc' TCL arguments.
 * Output:
 *  return        int     TCL_OK    - Normal completion.
 *                        TCL_ERROR - The interpreter result will contain
 *                                    the error message.
 */


/*.......................................................................
 * Implement the demo "function" command. This takes one of a set of
 * supported function-designations and displays it in the image window.
 *
 * Input:
 *  demo       Pgdemo *   The demo being serviced.
 *  interp Tcl_Interp *   The TCL interpreter of the demo.
 *  argc          int     The number of TCL arguments in argv[].
 *  argv         char **  An array of 'argc' TCL arguments.
 *                        argv[0] - A function designation chosen from:
 *                                   "cos(R)sin(A)"
 *                                   "sinc(R)"
 *                                   "exp(-R^2/20.0)"
 *                                   "sin(A)"
 *                                   "cos(A)"
 *                                   "(1+sin(6A))exp(-R^2/100)"
 * Output:
 *  return        int     TCL_OK    - Normal completion.
 *                        TCL_ERROR - The interpreter result will contain
 *                                    the error message.
 */


/*.......................................................................
 * Implement the demo "slice" command. This takes two pairs of image
 * world coordinates and plots a 1D representation of the currently
 * displayed function in the slice window.
 *
 * Input:
 *  demo       Pgdemo *   The demo being serviced.
 *  interp Tcl_Interp *   The TCL interpreter of the demo.
 *  argc          int     The number of TCL arguments in argv[].
 *  argv         char **  An array of 'argc' TCL arguments. There
 *                        should be 4 arguments, "x1 y1 x2 y2" where
 *                        x1,y1 and x2,y2 are the two end points of the
 *                        slice line.
 *
 * Output:
 *  return        int     TCL_OK    - Normal completion.
 *                        TCL_ERROR - The interpreter result will contain
 *                                    the error message.
 */