Chapter 14: Drawing label bars

Previous chapter          LLUs Home          Next chapter          Index

The Labelbar utility creates a specialized label consisting of a bar of filled areas that are labeled to correspond with areas filled by another utility. Label bars can be filled with black-and-white pattern fills, with color, or with both. Label bars are commonly used with contour plots and with other types of plots where area pattern fills or color are used to differentiate values in the plot.

Table of Labelbar user entry points

This module organizes the Labelbar routines according to their functions.

Drawing routine

LBLBAR: Draws a complete label bar.

Filling routine

LBFILL: Fills portions of the label bar. LBFILL is a user-modifiable routine.

Parameter setting and retrieving routines

LBGETI: Retrieves a Labelbar integer parameter value.
LBSETI: Sets a Labelbar integer parameter value.
LBGETR: Retrieves a Labelbar real parameter value.
LBSETR: Sets a Labelbar real parameter value.

Table of Labelbar parameters

Currently, Labelbar supports six parameters. Three can be retrieved by the LBGETI routine or set with the LBSETI routine, and three can be retrieved by the LBGETR routine or set with the LBSETR routine. For a more complete description of Labelbar parameters, see the labelbar_params man page or the Labelbar programmer document.

---------------------------------------------
Parameter  Brief description     Fortran type  
---------------------------------------------
CBL        Color of Box Lines    Integer       
CFL        Color of Fill Lines   Integer       
CLB        Color of LaBels       Integer       
WBL        Width of Box Lines    Real          
WFL        Width of Fill Lines   Real          
WLB        Width of LaBel lines  Real          
---------------------------------------------

Drawing the label bar

A single call to LBLBAR is all that is necessary to draw either horizontal or vertical label bars.

Simple label bars

Code segment from clblbr.f

1       DATA LAB1 /'.','here','go','can',':G:font','any','in',
2      + 'number','or','word','Any'/
3       DATA LAB2 /'.','boxes','between','lines','the','or','boxes',
4      + 'either','match','can','labels','that','Notice'/
5       DATA IFILL1 /11,10,9,8,7,6,5,4,3,2,1/
6       DATA IFILL2 /3,4,5,6,7,8,9,10,2,11,12,13,14,15/
7       CALL GSFAIS(1)
8       CALL SFSETR('AN',35.)
9       CALL SFSETI('TY',-4)
10      CALL LBLBAR(1,.05,.45,.05,.95,11,.3,1.,IFILL1,0,LAB1,11,1)
11      CALL SFSETI('TY',0)
12      CALL LBLBAR(1,.55,.95,.05,.95,14,.3,1.,IFILL2,1,LAB2,13,2)

Synopsis

      CALL LBLBAR (IHOV, XLEB, XREB, YBEB, YTEB, NBOX, WSFB, HSFB, LFIN, 
     +             IFTP, LLBS, NLBS, LBAB)

Arguments

IHOV

Integer, Input---An integer specifying whether the bar should be oriented horizontally or vertically.

0: Draw the bar horizontally.
1: Draw the bar vertically.

XLEB, XREB, YBEB, YTEB

Real, Input---Four values in the range 0.0 to 1.0 that specify the left, right, bottom, and top coordinates, respectively, in NDCs in which the entire bar, including labels, is to fit.

NBOX

Integer, Input---A value specifying the number of boxes into which the bar should be divided. All boxes are equal in size. A horizontal bar is divided into boxes by vertical lines, and a vertical bar is divided into boxes by horizontal lines. The boxes in a horizontal bar are ordered from left to right, and the boxes in a vertical bar are ordered from bottom to top. This ordering determines the sequence in which the boxes are filled and labeled. Box outlines can be omitted by using a negative value of NBOX.

WSFB, HSFB

Real, Input---0.0<=WSFB, HSFB<=1.0. WSFB specifies a fraction of the width of the box to be filled, and HSFB specifies a fraction of the height of the box to be filled. For example, if you use WSFB=0.333 and HSFB=1.0, the width of the filled portion of each box will be one-third of the box's width, and fill will extend all the way from the bottom of the box to its top. The exact position of each filled portion within its box depends on how you choose to label the bar (see the description of the argument LBAB below); positioning is automatically handled for you by LBLBAR.

LFIN

Integer array, Input---The list of fill indices, one for each box in the bar.

IFTP=0: The elements of LFIN will be passed to the Softfill subroutine SFSGFA as values for the argument ICI.
IFTP<>0: The elements of LFIN will be passed to the subroutine LBFILL as values for the argument INDX.

By default, LFIN is used as an argument of the GKS subroutine GSFACI to specify a color-fill index. It is affected by how the IFTP parameter is set.

IFTP

Integer, Input---Specifies how the filled portion of the boxes should be filled:

0: LBLBAR calls the Softfill routine SFSGFA to fill the box. The value of the Softfill internal parameter TY determines whether filling is done by calls to the GKS routine GFA, by drawing closely spaced colored lines to simulate solid fill, or by drawing lines at varying angles and spacings to form patterns.
<>0: The Labelbar routine LBFILL is called to fill the boxes. By default, LBFILL calls GKS routine GFA to color-fill the box.

LLBS

Character array, Input---A list of labels for the bar. If the number of labels is equal to the number of boxes, LBLBAR associates the labels with the boxes themselves. If the number of labels is one less than the number of boxes, LBLBAR associates the labels with the divisions between boxes. If the number of labels is one more than the number of boxes, LBLBAR associates the first label with the beginning of the bar, the last label with the end of the bar, and the labels in between with the divisions between the boxes.

NLBS

Integer, Input---The number of labels in the array LLBS. NLBS must be such thatNBOX-1<=NLBS<=NBOX+1.

LBAB

Integer, Input---Specifies on which side or sides of the bar the labels are to be drawn.

0: The bar is unlabeled.
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 repeated on both sides of the bar.

Discussion

LBLBAR calls the Plotchar routine PLCHHQ to draw the labels and automatically scales labels so they do not overlap one another or run outside the area for the label bar. Labels at the ends of the bar may run outside this area, however. Any font can be used; this is demonstrated by using the PLCHHQ code to set Greek characters for the word "font" in line 1 of the clblbar.f code segment.

When IFTP is zero, as shown in line 10, LBLBAR does fill by calling the Softfill routine SFSGFA. The argument array LFIN, called IFILL1 in the clblbar example, contains the values that are passed to SFSGFA as values of its argument ICI. In line 5, values of IFILL1 go from highest to lowest, so that the most densely filled boxes will be at the bottom of the label bar. Before calling LBLBAR, line 8 sets the Softfill parameter to draw lines at an initial angle of 35 degrees, and line 9 sets the Softfill parameter to draw lots of crisscrossing lines. For a detailed explanation of the use of TY, see the module titled "Choosing how fill is done" in Chapter 13 "Area filling with GKS and Softfill."

By default, TY=0; this forces SFSGFA to do fill by calling the GKS subroutine GFA. GFA does either hollow, solid, or hatch fill. Hollow fill (only boundaries are drawn) is the GKS default, but you can change the type of fill used by calling the GKS subroutine GSFAIS. Notice that line 7 uses GSFAIS to do solid fill. Line 12 draws the label bar on the right side of the plot; this call to LBLBAR uses the GKS color-fill option by setting IFTP to 1.

Advanced filling of label bars

This module covers material that most readers will not need. When the LBLBAR argument IFTP<>0, LBFILL is called to fill the label bar. The default version of LBFILL does color fill by calling GSFACI with color indices set in LBLBAR argument LFIN, and GKS routine GFA.

Special fill example

Code segment from clbfil.f

1       SUBROUTINE LBFILL (IFTP,XCRA,YCRA,NCRA,INDX)
2       IF (INDX.EQ.1) THEN
3          CALL SFSETR ('SP - SPACING OF FILL LINES',.012)
4          CALL SFSETI ('DO - DOT-FILL FLAG',0)
5          CALL SFWRLD (XRA,YRA,NRA,DST,500,IND,500)
6          CALL SFSETR ('SP - SPACING OF FILL LINES',.006)
7          CALL SFSETI ('DO - DOT-FILL FLAG',1)
8          CALL SFNORM (XRA,YRA,NRA,DST,500,IND,500)
9       ENDIF

Synopsis

      CALL LBFILL (IFTP, XCRA, YCRA, NCRA, INDX)

Arguments

IFTP: Integer, Input---A fill-type selector. When LBFILL is called by LBLBAR, this will be the argument IFTP from your call to LBLBAR, and it will always be nonzero.
XCRA(NCRA), YCRA(NCRA): Real arrays, Input---The X and Y values, in NDCs, that define an area to be filled. The last point is a duplicate of the first.
NCRA: Integer, Input---The number of points defining the area to be filled. When LBFILL is called by LBLBAR, its value will always be 5.
INDX: Integer, Input---A color index or pattern selector. When LBFILL is called by LBLBAR, this will always be an element from the array LFIN in your call to LBLBAR. Its value may be used as a color index or as a pattern selector.

Discussion

LBFILL is called when the LBLBAR argument IFTP is nonzero. It is called once for each filled portion of the label bar. It is expected to fill that portion of the box defined by the argument arrays XCRA and YCRA. Here is the default version of the routine:

      SUBROUTINE LBFILL (IFTP, XCRA, YCRA, NCRA, INDX)
      DIMENSION XCRA(*), YCRA(*)
      CALL GSFACI (INDX)
      CALL GFA (NCRA-1, XCRA, YCRA)
      RETURN
      END

The default version fills an area by calling GFA. The argument INDX is used as a color index. In the clbfil.f code segment, however, INDX determines which special pattern fill is to be used. Lines 3 through 8 use several Softfill routines to draw alternating lines and dots.

Setting and retrieving Labelbar parameters

Labelbar has four parameter setting and retrieving routines. Labelbar parameters control things like line width and color, as well as text width and color. All Labelbar parameters are described in the next module, in the labelbar_params man page, and in the Labelbar programmer document.

Synopsis

 
      CALL LBGETI (PNAM, IVAL)
      CALL LBSETI (PNAM, IVAL)
      CALL LBGETR (PNAM, RVAL)
      CALL LBSETR (PNAM, RVAL)

Routines

LBGETI: Retrieves an integer parameter value.
LBSETI: Sets an integer parameter value.
LBGETR: Retrieves a real parameter value.
LBSETR: Sets a real parameter value.

Arguments

PNAM: Character String, Input---A character string denoting the parameter name. The parameter name is enclosed by single quotation marks in Fortran calls to ensure that it is treated as a string rather than a real or integer variable.
RVAL: Real, Input or Output---A real value used for setting or retrieving a parameter value.
IVAL: Integer, Input or Output---An integer value used for setting or retrieving a parameter value.

Setting Labelbar parameters

Labelbar currently has six parameters, three for controlling line or character width, and three for controlling line or character color.

Modified label bar

Code segment from clblpr.f

1       CALL COLOR
2       CALL LBSETI('CBL',1)
3       CALL LBSETI('CFL',15)
4       CALL LBSETI('CLB',12)
5       CALL LBSETR('WBL',1.5)
6       CALL LBSETR('WFL',2.0)
7       CALL LBSETR('WLB',5.0)
8       CALL SFSETI('TY',-2)
9       CALL SFSETR('AN',45.)
10      CALL LBLBAR(0,.05,.95,.05,.95,5,1.,.3,IFILL1,0,LAB1,5,1)

Synopsis

      CALL LBSETI('CBL',icbl)
      CALL LBSETI('CFL',icfl)
      CALL LBSETI('CLB',iclb)
      CALL LBSETR('WBL',wbl)
      CALL LBSETR('WFL',wfl)
      CALL LBSETR('WLB',wlb)

Arguments

CBL: Integer---The color of box lines flag sets the color index of the lines defining the boundaries of the boxes in a label bar. By default CBL=-1, and the current polyline color index will be used to draw the lines.
CFL: Integer---The color of fill lines flag sets the color index for Softfill lines drawn by Labelbar. This option is only used if IFTP=0, and -4<=TY<=-1. By default, CFL=-1; the current polyline color index will be used to draw the lines.
CLB: Integer---The color of labels flag sets the color index for text drawn by Labelbar. By default CLB=-1, and the current text color index will be used to draw the labels.
WBL: Real---The width of box lines parameter sets the line width scale factor for box lines.
WFL: Real---The width of fill lines parameter sets the line width scale factor for fill lines drawn by Softfill. This parameter is only used if IFTP=0, and -4<=TY<=-1.
WLB: Real---The width of label parameter sets the line width scale factor for drawing text.

Discussion

The line width scale factor mentioned in WBL, WFL, and WLB sets the line width so that it is the scale factor times the "normal" line width. For example, if WLB is set to 3.0, then the box line width will be three times as thick as the normal line width on most output devices.

Lines 5, 6, and 7 of the clblpr.f code segment set the box lines to be 1.5 times the normal thickness, cross-hatch lines to be twice the normal thickness, and text lines to be five times the normal thickness. Line 1 sets up the color table. Then lines 2 through 4 use it to set box line, cross-hatch line, and text colors, respectively. Lines 8 and 9 set Softfill options to do cross-hatching at a 45-degree angle. Line 10 draws the label bar.

Previous chapter          LLUs Home          Next chapter          Index