Function:     GgiPlotColorEditor

Purpose:      Create/manipulate Ggi colormap editing element for plot fields.

Category:     USER-INTERFACE

File:         ggi.src

Author:       J.P. Terlouw

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

              editor = GgiPlotColorEditor(opcode, ...);

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

              The following variants exist:

              - create a colormap editor:

                  editor = GgiPlotColorEditor(ggiCreate, ci, nc);

                           int ci - starting color index                  
                           int nc - number of color indices
                           int bl - BLANK color

              - specify data limits:

                  editor = GgiPlotColorEditor(ggiLimits, id, v1, v2); 

                           ident id - existing colormap editor
                           float v1 - data value corresponding with lowest
                                      color index
                           float v2 - data value corresponding with highest
                                      color index

              - specify data units string:

                  editor = GgiPlotColorEditor(ggiUnits, id, units);

                           ident id    - existing colormap editor
                           char *units - zero-terminated character string

              - apply current settings to currently selected PGPLOT device:

                  editor = GgiPlotColorEditor(ggiApply, id);

                           ident id - existing colormap editor

              - obtain the current settings to be used in the application:

                  editor = GgiPlotColorEditor(ggiGetMap, id, nc,
                                              reds, greens, blues,
                                              bred, bgreen, bblue);

                            ident id - existing colormap editor
                            int   nc - number of colors to be obtained
                            float reds[nc], greens[nc], blues[nc]
                                     - arrays receiving the colormap components
                            float *bred, *bgreen, *bblue
                                     - variables receiving the blank color,
                                       or -1.0 if not available

Description:  GgiPlotColorEditor creates or manipulates a colormap editor.
              Such an editor operates on the part of the master color table
              specified by the arguments when the element is created.
              It consists of a color wedge, sliders which can manipulate
              the colormap's slope and shift, menus for choosing the type
              of color map and the scaling method, buttons for inverting
              and resetting the map, a button which pops up a window for
              x-y color map manipulation and a button whichs pops up a file
              browser for selecting a user-defined color lookup table file.
              If argument "bl" is larger than 15, three extra elements
              are added:  a menu and an input field to specify a color,
              and a small plotfield showing this color.
              "bl" is assumed to be the color index for BLANK data values.
              It should be specified by calling PGSBCI in the plot for
              which the color map is being manipulated.

              When GgiPlotColorEditor is called with opcode ggiLimits and
              different v1 and v2, these values are used to annotate the
              wedge. Opcode ggiUnits can be used to display a text next to
              the wedge, e.g. specifying the data units.

              Opcode ggiApply can be used to apply the current settings to
              the currently selected PGPLOT device. This can be useful when
              for instance a hardcopy of a plot is being generated in which
              the current color setting is to be used. The color index range
              to be used must be specified before by calling PGSCIR.

              Opcode ggiGetMap is used to make the current setting available
              to the application. This can be useful when the application
              needs to transfer this information to an other program.

Keywords:     The state of the element is controlled by a number of
              user input keywords of the form "CE_<attr><n>=", where
              <attr> is the name of an attribute like "SLOPE" or "SHIFT".
              and <n> it the instance sequence number, starting with 1.
              The application may read and write these keywords.
              
Related documents:
              GgiPlotField.dc2, GgiPlotColors.dc2, GgiPlotMapColors.dc2


Updates:      Sep 17, 1999: JPT, Document created.
              Oct  4, 1999: JPT, BLANK specification implemented.
              Jul 12, 2000: JPT, Explained keywords.
              Sep  5, 2000: JPT, Implemented ggiGetMap.
              Dec  8, 2001: JPT, Added colormap "Renzo"
              Mar  7, 2002: JPT, Added file browser for user LUTs.
              Jun 25, 2004: JPT, Implemented x-y manipulation.