Function:     GgiPrompter

Purpose:      Create a Ggi prompter element

Category:     USER-INTERFACE

File:         ggi.src

Author:       J.P. Terlouw

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

              GgiPrompter(keydir, message);

                 keydir  -  user input keyword or directive
                 message -  message associated with call

Description:  GgiPrompter creates a prompter. A prompter is a pop-up window
              in which a simple dialog can take place. It consists of a
              one-line prompt text, a type-in field, a text area for
              extra explanation and a cancel- and ok-button.

              As long as a 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
                 GgiPrompter() are the user input keyword and a prompt
                 message.
              2. reject the given input or ask confirmation. Here argument
                 keydir 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 keydir value "ACCEPT". This causes
                 the prompter to be removed, after which interaction
                 with other Ggi elements is possible again.

              Apart from using the "AGAIN"-direcitive, 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.

              When active, the prompter writes any value typed in the input
              field to the keyword specified when the prompter was created.
              When the user presses the cancel-button, an empty value is
              written to the 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:      Mar 31, 1999: JPT, Document created.
              Mar 10, 2000: JPT, Internal keyword names standardized.