NAME

       NGSRAT - save/restore/set NCAR GKS primitive attribute values in toto.

SYNOPSIS

       CALL NGSRAT(IOPT, IAT, RAT)

C-BINDING SYNOPSIS

       #include <ncarg/ncargC.h>

       void c_ngsrat(int iopt, int *iat, float *rat)

DESCRIPTION

       IOPT        (an input variable of type INTEGER) indicating the desired action:

                     = 0   save the current settings of all attributes internal to the
                           subroutine, i.e. not in the IAT and RAT arrays.

                     = 1   restore the context from the most recently saved state.

                     = 2   return the current context in the output arrays IAT (integer
                           attributes) and RAT (floating-point attributes) as follows:

                           IAT contains integer GKS attribute settings as per:

                             IAT( 1) = Clip indicator

                             IAT( 2) = Line type

                             IAT( 3) = Polyline color index

                             IAT( 4) = Marker type

                             IAT( 5) = Polymarker color index

                             IAT( 6) = Text font

                             IAT( 7) = Text precision

                             IAT( 8) = Text color index

                             IAT( 9) = Text path

                             IAT(10) = Text horizontal alignment

                             IAT(11) = Text vertical alignment

                             IAT(12) = Fill area interior style

                             IAT(13) = Fill are style index

                             IAT(14) = Fill area color index

                           RAT contains REAL GKS attribute settings as per:

                             RAT( 1) = Linewidth scale factor

                             RAT( 2) = Marker scale factor

                             RAT( 3) = Character expansion factor

                             RAT( 4) = Character spacing

                             RAT( 5) = Character height in world coordinates

                             RAT( 6) = Character up vector, X component in world coordinates

                             RAT( 7) = Character up vector, Y component in world coordinates

                     = 3   set the context to the values specified in the IAT and RAT arrays (as
                           described above).

       IAT         An integer array, of length 14, that has meaning only if IOPT equals 2 or 3.
                   The elements of the IAT array are described in the above description of IOPT.

       RAT         A real array, of length 7, that has meaning only if IOPT equals 2 or 3.  The
                   elements of the IAT array are described in the above description of IOPT.

USAGE

       If you want to save the state of the NCAR GKS primitive attribute settings, call NGSRAT
       with a first argument of 0.  When the first argument is 0, the IAT and RAT arrays (second
       and third arguments) are ignored and the state values are stored internally to NGSRAT.

       To restore the NCAR GKS primitive attribute values to what they were as of the last time
       NGSRAT was called with argument IOPT = 0, then call NGSRAT with first argument of 1.  IAT
       and RAT are ignored in this case.

       If you call NGSRAT with a fist argument of 2, then the current settings of the NCAR GKS
       primitive attribute values are returned in arrays IAT and RAT as per the description of
       IAT and RAT above.

       If you call NGSRAT with a fist argument of 3, then arrays IAT and RAT must be supplied and
       the values therein will be used to set the NCAR GKS primitive attribute values as per the
       description of IAT and RAT above.

       A common use of NGSRAT would be in conjunction with NGMFTC and NGREOP for saving the GKS
       state after writing to one metafile, writing to a new metafile, and then restoring the GKS
       state when reopening the initial metafile.

EXAMPLES

       The following sequence:

               CALL NGSRAT(0,IAT,RAT)

                 ... do some setting and drawing

               CALL NGSRAT(1,IAT,RAT)

       would save the values of all NCAR GKS primitive attributes before the code that does
       setting and drawing and then restore the attribute values after the setting and drawing.

       Use the ncargex command to see the following relevant example: pgkex27.

ACCESS

       To use NGSRAT or c_ngsrat, load the NCAR Graphics libraries ncarg, ncarg_gks, and ncarg_c,
       preferably in that order.

MESSAGES

       NGSRAT issues no messages apart from potential illegal setting of the attribute values
       when IOPT = 3.

SEE ALSO

       Online: ngmftc(3NCARG), ngreop(3NCARG),

       Hardcopy: NCAR Graphics Fundamentals, UNIX Version.

COPYRIGHT

       Copyright (C) 1987-2009
       University Corporation for Atmospheric Research
       The use of this Software is governed by a License Agreement.