Function:     GgiPlotPrompter

Purpose:      Create a Ggi plot prompter element

Category:     USER-INTERFACE

File:         ggi.src

Author:       J.P. Terlouw

Use:          
              #include "ggi.h"
              char *filekeydir, *devkey, *message;

              GgiPlotPrompter(filekeydir, devkey, message);

                 filekeydir  -  user input keyword for a plot file name.
                 devkey      -  user input keyword for plot device name.
                 message     -  message associated with call.

Description:  GgiPlotPrompter creates a plot prompter. A plot prompter is a
              pop-up window in which a dialog takes place for specifying a
              PGPLOT device name for hardcopy plots and  an optional file name.

              It consists of:
              - a one-line prompt text;
              - a type-in field, where a filename can specified
                (this file is usually a PostScript file);
              - a menu from which any available hardcopy PGPLOT device
                can be selected;
              - a text area for extra explanation and error messages;
              - a "CANCEL" button;
              - a "PLOT"-button.

              As long as the prompter is active, interaction with other
              Ggi elements is not possible. This also implies than only
              one prompter can be present at any time.

              When using a prompter, a number of phases can be identified:

              1. create the prompter. In this case the arguments to
                 GgiPlotPrompter() are the file name- and device keywords
                 and a prompt message.
              2. reject the given input or ask confirmation. Here argument
                 filekeydir has the value "AGAIN" and message can be a one- or
                 two-line message with an explanation. This phase is
                 optional.
              3. accept the input with filekeydir value "ACCEPT". This causes
                 the prompter to be removed, after which interaction
                 with other Ggi elements is possible again.

              Apart from using the "AGAIN"-directive, input can also be
              rejected by Hermes or by calling reject_c() from the program.
              The prompter will then display the message associated with this
              rejection.

              Before the "PLOT"-button can be pressed, the user must first
              select a PGPLOT device name. This name is then written to
              the 'devkey' keyword.
              When the "PLOT"-button is pressed, the prompter writes any
              value typed in the input field to the 'filekeydir' keyword.
              When the user presses the "CANCEL"-button, an empty value is
              written to this keyword.

Keywords:     The following keywords are reserved for internal use:
              all keywords starting with "_GGIPR" and with "_GP".

See also:     Example program in the TESTBED section of ggiprompter.c.

Updates:      May 28, 1999: JPT, Document created.
              Mar 10, 2000: JPT, Internal keyword names standardized.