Function:     GgiPlotField

Purpose:      Create Ggi element implementing a PGPLOT window

Category:     USER-INTERFACE, GRAPHICS

File:         ggi.src

Author:       J.P. Terlouw

Use:
              #include "ggi.h"
              ident plotfield;
              char *devicename;
              int  width, height;

              plotfield = GgiPlotField(devicename, width, height);

                plotfield   -  'handle' by which element can be referenced.
                devicename  -  device name to be used in later PGBEG call.
                width       -  horizontal size of window. If zero, the
                               existing element corresponding with
                               'devicename' is returned.
                height      -  vertical size of window.

Description:  GgiPlotField creates a plot window which can be used with
              the PGPLOT routines. Currently the maximum number of such
              windows is 20.
              
              All plot windows must have been created before any PGPLOT
              routine is called. Windows created later will be inoperative.

              The PGPLOT capabilities are a superset of those of the X11
              plot server (plserver), except that there is no standard
              cursor capability because this is incompatible with the
              event-driven paradigm supported by Ggi.
              Cursor interaction can be obtained using a callback mechanism
              implemented by the function ScheduleGgiPlotCursor().

              Initially 16 standard colors are available. If more colors
              are needed, GgiPlotColors() can be called to adjust the
              number of colors.

              A plotfield can be made availabe for other tasks by
              'exporting' it with the function GgiPlotExport().

Related documents:
              GgiPlotColors.dc2, GgiPlotXor.dc2, ScheduleGgiPlotCursor.dc2,
              DescheduleGgiPlotCursor.dc2, GgiPlotExport.dc2.

Updates:      Feb 25, 1998: JPT, Document created.
              Mar  1, 1998: JPT, Return existing element for zero width.
              Jan 14, 1999: JPT, Document modified for GgiPlotColors.
              May  9, 2003: JPT, Regenerate previously covered parts of window.
              Aug 13, 2004: JPT, Export function implemented.
              Mar 23, 2006: JPT, Optimized expose event handling.
              Jun  2, 2010: JPT, Avoid some X servers' XGetImage inefficiency.