!=====================================================================
! NGLB: Labelbar, A Package of Routines to Draw Labelled Bars
!=====================================================================
!
! LabelBar, a small package of NCAR Graphics, that allow a user to
! create a labelled, filled, rectangular bar to serve as a key for a
! filled plot. The bar may be positioned horizontally or vertically in
! any desired portion of the plotter frame. Rectangular boxes along the
! bar are filled with different colors or patterns. Labels are written
! next to the bar in such a way as to be associated with the boxes or
! with the lines dividing the boxes from each other.
!
! A label bar is drawn by a single call to a routine called NG_LBLBAR.
! Exactly what a given call does is determined by the values of the
! arguments in the call and by the values of SIX INTERNAL PARAMETERS.
!
! The routine NG_LBGET1 allows a user to retrieve the values of these
! internal parameters and the routine NG_LBSET1 allow a user to give
! new values to the internal parameters. The routine NG_LBSET0 allows
! a user to reset these internal parameters to its default values.
!
!---------------------------------------
!
! SUBROUTINE NG_LBRSET()
!
! SUBROUTINE NG_LBSETI( WHCH, IVAL )
! SUBROUTINE NG_LBSETR( WHCH, RVAL )
!
! SUBROUTINE NG_LBGETI( WHCH, IVAL )
! SUBROUTINE NG_LBGETR( WHCH, RVAL )
!
! SUBROUTINE NG_LBLBAR( IHOV, XLEB, XREB, YBEB, YTEB, NBOX, WSFB, HSFB,&
!                       LFIN, IFTP, LLBS, NLBS, LBAB, LBFILL )
!
!---------------------------------------------------------------------
!
! Internal Parameters: LABELBAR has six internal parameters
!
!   'CBL' I Color of box lines. The default value is -1.
!   'CFL' I Color of fill lines. The default value is -1.
!   'CLB' I Color of labels. The default value is -1.
!
!   'WBL' R Width of box lines. The default value is 0.
!   'WFL' R Width of fill lines. The default value is 0.
!   'WLB' R Width of label lines. The default value is 0.
!
!---------------------------------------------------------------------
!
! SUBROUTINE NG_LBLBAR( IHOV, XLEB, XREB, YBEB, YTEB, NBOX, WSFB, HSFB,&
!                       LFIN, IFTP, LLBS, NLBS, LBAB, LBFILL )
!
!   INTEGER,      INTENT(IN) :: IHOV, NBOX, IFTP, NLBS, LBAB
!   REAL,         INTENT(IN) :: XLEB, XREB, YBEB, YTEB, WSFB, HSFB
!   INTEGER,      INTENT(IN) :: LFIN(ABS(NBOX))
!   CHARACTER(*), INTENT(IN) :: LLBS(NLBS)
!
!   EXTERNAL :: LBFILL
!   OPTIONAL :: LBFILL
!
! Arguments:
!
!   Routine to draw a horizontal or vertical label bar to serve as a key
!   for a solid-filled plot.
!
!   IHOV - Orientation of label bar
!
!          = 0, a horizontal label bar is to be drawn,
!
!          otherwise, a vertical label bar is to be drawn.
!
!   XLEB - a value between 0 and 1, specifying the position of the left
!          edge of the entire bar including labels.
!
!   XREB - a value between 0 and 1, specifying the position of the right
!          edge of the entire bar including labels.
!
!   YBEB - a value between 0 and 1, specifying the position of the bottom
!          edge of the entire bar including labels.
!
!   YTEB - a value between 0 and 1, specifying the position of the top
!          edge of the entire bar including labels.
!
!   NBOX - its absolute value is the number of boxes into which the bar
!          is to be divided.
!
!          > 0, the boxes will be outlined after being filled;
!
!          < 0, the boxes will not be outlined.
!
!   WSFB - the width (WSFB) and height HSFB), respectively, of each little
!   HSFB   solid-filled box, as fractions of the rectangles resulting from
!          the division of the bar into ABS(NBOX) pieces.
!
!   LFIN - a list of indices, each of which specifies, in some manner,
!          how one of the solid-filled boxes is to be filled.
!          (For example, each may be a color index.)
!
!   IFTP - the type of solid fill to be used.
!
!          If IFTP is zero, the routine NG_SFSGFA, in the package SOFTFILL,
!          will be called, with an index from LFIN as the value of the
!          argument ICI.  (By default, this will result in color fill; the
!          value of the SOFTFILL internal parameter 'TY' may be changed to
!          select some other kind of fill by SFSGFA.)
!
!          If IFTP is non-zero, the user-replaceable routine LBFILL (an
!          optional dummy subprogram) will be used to fill the boxes;
!          the default version of this routine just does color fill.
!
!   LLBS - a list of labels for the solid-filled boxes.
!
!   NLBS - the number of labels in the list LLBS.
!
!          If NLBS is equal to ABS(NBOX)-1, then label I applies to the
!          line separating box I from box I+1.
!
!          If NLBS is equal to NBOX, then label I applies to box I.
!
!          If NLBS is equal to ABS(NBOX)+1, then labels 1 and NLBS apply
!          to the left and right ends (if IHOV is non-zero, the bottom
!          and top ends) of the whole color bar; for values of I not
!          equal to 1 or NLBS, label I applies to the line separating
!          box I-1 from box I.
!
!   LBAB - a flag specifies on which side or sides of the bar the labels
!          are to be written.
!
!          = 0, the bar is to be unlabelled,
!
!          = 1, the labels are to be below a horizontal bar or to the
!               right of a vertical bar,
!
!          = 2, the labels are to be above a horizontal bar or to the
!               left of a vertical bar
!
!          >=3, the labels are to be on both sides of the bar.
!
!   LBFILL - the user defined fill routine should be PRESENT for IFTP
!            is non-zero.
!
!          This routine is called by NG_LBLBAR when argument IFTP is
!          non-zero. LBFILL is called once for each sub-box in the label
!          bar, using a statement of the form
!
!            CALL LBFILL( IFTP, XCRA, YCRA, NCRA, INDX )
!
!          and is expected to fill the sub-box defined by its arguments.
!
!          IFTP (an input expression of type INTEGER) is just the value
!          of the argument IFTP from the user's call to NG_LBLBAR.
!
!          XCRA and YCRA (input arrays of type REAL) are real arrays
!          containing the X and Y coordinates of four points defining
!          a rectangular box which is to be filled in some manner.
!
!          NCRA (an input expression of type INTEGER) is the number of
!          points defining the rectangular box. Its value will always
!          be five.
!
!          INDX (an input expression of type INTEGER) is one of the
!          indices from the array LFIN, in the call to NG_LBLBAR. Its
!          value may be used as a color index or as a pattern selector.
!
!---------------------------------------
!
! SUBROUTINE LBFILL( IFTP, XCRA, YCRA, NCRA, INDX )
!
!   INTEGER, INTENT(IN) :: IFTP, NCRA, INDX
!   REAL,    INTENT(IN) :: XCRA(NCRA), YCRA(NCRA)
!
! This routine is called by NG_LBLBAR when NG_LBLBAR's argument IFTP
! is non-zero. LBFILL is called once for each sub-box in the label
! bar, using a statement of the form
!
!     CALL LBFILL( IFTP, XCRA, YCRA, NCRA, INDX )
!
! and is expected to fill the sub-box defined by its arguments.
!
! Arguments:
!
!   IFTP - the value of the argument IFTP from the call to NG_LBLBAR.
!
!   XCRA - the X/Y coordinates of five points defining a rectangular
!   YCRA   box which is to be filled in some manner. The fifth point
!          defined by these arrays will always be a duplicate of the
!          first.
!
!   NCRA - the number of points defining the rectangular box. Its
!          value will always be five.
!
!   INDX - one of the indices from the array LFIN, in the user's call
!          to NG_LBLBAR. Its value may be used as a color index or as
!          a pattern selector.
!
!=====================================================================
! Refer "NCAR menu" for interfacing LABELBAR in detail
!=====================================================================