Function:     GgiTextMenu

Purpose:      Create Ggi menu element returning label text instead of index.

Category:     USER-INTERFACE

File:         ggi.src

Author:       J.P. Terlouw

Use:          
              #include "ggi.h"
              ident menu;
              char *keyword, *message, **labels;

              menu = GgiTextMenu(keyword, message, labels);

                 menu     - 'handle' by which element can be referenced.
                 keyword  -  user input keyword.
                 message  -  help text which pops up when the pointer stays
                             in the input area for some time.
                 labels   -  a NULL-pointer terminated list of pointers to
                             the menu entry texts.

Description:  GgiTextMenu creates a text menu element.

              When a menu entry is selected, the element writes the label
              text of the selected entry to the supplied keyword.
               
              The label texts pointed to bu the argument 'labels' mus remain
              valid as long as the element is used, i.e. it should be 
              declared static or have been created on the heap.
              
              As with other menus, the label texts can be modified later
              with GgiMenuLabels, but this does not affect the values which
              will be written to the keyword. The number of new labels must
              not exceed the original number.

Example:      Suppose you need a menu to specify a line width in a plot program.
              This can be created as follows:

                 static char *labels[] = {"1", "2", "4", NULL};
                 menu = GgiTextMenu("WIDTH=", "Line width", labels);

              In this menu the label texts are the values which will be
              assigned to the keyword WIDTH=. These values can subsequently
              be read with e.g. userfint(). If you don't like numbers as
              label texts, you can modify these texts, e.g.:

                 char *newlabels[] = {"Thin", "Normal", "Wide", NULL};
                 (void)GgiMenuLabels(menu, newlabels);

Updates:      Aug 18, 2000: JPT, Document created.