Function:     GgiInset

Purpose:      Ggi element for specifying set, subset and box information.

Category:     USER-INTERFACE

File:         ggi.src

Author:       J.P. Terlouw

Use:
              #include "ggi.h"
              ident element;
              int   opcode;

              element = GgiInset(opcode, ...);


              ... is a variable argument list of which the elements
                  depend on the value of opcode.

              The following variants exist:

              - create the element:

                  element = GgiInset(ggiCreate, name, inset, box, message);

                            char *name   - user input keyword for set name
                            char *inset  - keyword for set, subset
                            char *box    - keyword for box or NULL
                            char message - explanatory message


              - delete the element:

                  (void)GgiInset(ggiDelete, element);

                            ident element - element to be deleted


              - find existing element, given set name keyword:

                  element = GgiInset(ggiIdent, name);

                            char *name - user input keyword for set name
                          

              - set dimensionality:

                  element = GgiInset(ggiNdims, element, ndim);

                            ident element - element to be modified
                            int ndim      - initial dimensionality

              - set immediate close after pressing OK button:

                  element = GgiInset(ggiCloseOnOK, element);

                            ident element - element to be modified 


Description:  GgiInset creates or manipulates a pop-up window for specifying
              set, subset and box information. This window initially consists
              of an explanatory text at the top, an input field for the set
              name, input/output fields for set, subset and box, a browse
              button, close and ok-buttons and an empty area.
                    When the user enters a set name, the empty area will
              be filled with as many lines as there are axes in the set.
              Each line consists of a text with the axis name, two buttons
              for selecting subset- or box mode, an input field and a text
              showing the range of the axis. If subset mode is selected,
              the corresponding axis name is incorporated in the set, subset
              specification, together with the contents of the input field.
              In box mode, the contents of the input fields is used for
              the box field. When the user is satisfied with the set, subset
              and box specifications, the ok-button can be pressed which
              causes the 'inset' and 'box' keywords to be written.
                    If 'box' is specified as NULL, there will be no box
              input/output field and box mode buttons. In this case only set
              and subsets can be specified.
                    In case the dimensionality has been set with opcode
              ggiNdims, the first 'ndim' axes are preset as box axes and
              the remaining axes as subset axes. If the set has fewer than
              'ndim' axes, an error message is displayed.
                    The browse button causes a file browser to be popped up
               from which a set name can be selected.

Keywords:     All keywords beginning with "_GGIIS" are reserved for internal
              use by GgiInset.
              
Updates:      Nov 25, 1999: JPT, Document created.
              Dec  9, 1999: JPT, Improved internal keyword scheme.
              Mar 30, 2000: JPT, Immediate close implemented.
              Jul 11, 2000: JPT, Header button added.
              Oct  2, 2000: JPT, Missing "close-on-ok" implemented.