Chapter 11: Drawing text and symbols

There are several methods for drawing text and symbols on a plot and controlling their characteristics, such as their color, angle, font, and position. The following modules demonstrate how to draw text and symbols and set their characteristics using GKS and higher level routines.

Defines the default list of "special colors" used by PLCHHQ in drawing certain characters from the filled fonts. At the time of this printing, however, there are no characters for which the special colors are used. In the future there will be, and the routine will be of more use.

PCMPXY

Routine called by PLCHHQ and PLCHMQ to request mapping of characters from one X/Y coordinate system to another when the mapping flag MA is nonzero. Users can supply their own version of this routine to create their own mappings.

Character expression, Input---A string that specifies the name of the parameter. This string begins with either one of the two-character mnemonics listed in the preceding parameter table or a two-character mnemonic followed by an index enclosed in parentheses when referencing a parameter with an array type. Only these leading characters are examined by Plotchar and must all be either uppercase or lowercase.

CVAL

Character, Input or Output---A character value. The characters must all be uppercase or lowercase when used as input.

Most of the parameters are singly dimensioned, but a couple of them are arrays. The name of a particular element of a parameter array is formed by appending the index of the element, enclosed in parentheses, to the two-character name of the parameter array. If the index is a constant, this is easily done, however, if the index is a variable, forming the name is rather clumsy. The function PCPNWI is provided to make things a little easier for the user.

The following function call could be used to retrieve the name of the element of a parameter array:

PCPNWI (PNAM, IPAI)

PNAM is the parameter name and IPAI is an integer variable containing the desired index value. Note that any routine that uses PCPNWI must contain the following declaration:

CHARACTER * 16 PCPNWI

So, for example if IPAI equals 3, then the value of:

PCPNWI ('CC', IPAI)

is the character string 'CC(3)' (padded with blanks to the right), and the call:

PCSETI (PCPNWI ('CC', IPAI), 62)

sets element 3 of the CC array to 62. In this case, it would be easier to write:

PCSETI (CC(3), 62)

but that misses the point that the variable IPAI will not always be known.

GTX is the GKS routine for drawing text. Text attributes like color, spacing, font, and so forth can be set by using GKS attribute-setting routines and then calling GTX. This module demonstrates how to set attributes and draw text with GKS routines.

GTX is used to draw GKS text-output primitives at the coordinates specified by XCOORD and YCOORD. There are several attribute-setting routines for selecting the size, font, precision, and orientation of text. For detailed information about using these routines, see the User's Guide for NCAR GKS-0A Graphics.

The fgkgtx.f code segment plots the strings "Brazil" and "Chile" in the graphic. This code segment demonstrates how to set the character color, spacing, height, orientation, and font.These attributes must be set prior to making the GTX call that draws the text.

Line 1 calls a routine that creates a color table for specifying the character color.

Line 2 sets the character color. The argument passed to the GSTXCI routine is an index in the color table created in line 1. All text drawn with GTX will have this color until GSTXCI is called again.

Line 3 sets the character height. The argument to GSCHH is a real value representing the character height in user coordinates. This value is any real number greater than 0.

Line 4 sets the font. The first argument to GSTXFP is the integer value that determines the font. The default is 1, which specifies the ASCII font. This example sets the font to Hershey Gothic English. The second argument sets the type of precision used in subsequent calls to the GTX output primitive. The value 2 (the default) specifies the best possible stroke precision. Valid font numbers are 1 and any integer in the range -2 to -20. The absolute value of these font numbers corresponds to the fontcap databases 1 through 20 listed in a later module.

Line 5 calls the Ezmap routine MAPTRA; this converts the input latitude and longitude values into coordinates that can be used in the GTX routine. The MAPTRA call should be made after the Ezmap routine MAPINT or MAPDRW is called.

Line 6 draws the string "Brazil" using the attributes set above.

Line 8 sets the text color. In this segment the color is the same as the one used for the "Brazil" string, so this call is redundant.

Line 9 sets the character height.

Line 10 selects the Hershey complex Roman font. Please see the module "Fontcap databases 1-20" for a list of all valid GTX fonts.

Line 11 converts the input coordinates from latitude/longitude values to coordinates that can be used by GTX.

Line 12 establishes a vector direction parallel to a vertical line through a character's center. This sets the angle at which text will be drawn. The first argument is the X coordinate of a vector tip, and the second is the Y coordinate. The vector tail is at (0, 0). Thus the arguments 0.0, 1.0 would imply normal character positioning. This example, however, sets the vector at almost a right angle to this, and, therefore, any strings will be drawn in a direction that runs from the bottom to the top of the plot.

Line 13 sets the amount of white space between characters. The argument is a fraction of the character height, so in this example there are two white spaces between every character in the string "Chile."

The Plotchar routine PLCHLQ (or PCLOQU) is a higher level NCAR Graphics routine that draws characters of "low quality" by calling the GKS character-drawing routines. This module demonstrates how to draw text with PLCHLQ and how to select fonts, character size, and text color.

The function codes, like those described later in the "Drawing text with the PLCHHQ routine" module, may not be used.

The number of characters in CHRS is taken to be LEN(CHRS). Use the FORTRAN 77 substring notation CHRS(m:n) to draw only characters m through n (where m and n are integer expressions) from the CHRS character string.

SIZE

Real, Input---Defines a multiplier for character size based upon the following values of SIZE:

<=0.

The absolute value specifies the character size as a multiple of a default digitized size on a 1024x1024 grid on which blanks are 16 units wide.

0.<SIZE<1.

Specifies the desired width of a blank as a fraction of the distance across the plotter frame.

>=1.

Specifies the desired width of a blank in plotter coordinates, as defined by default or by a call to the SPPS routine SETI.

ANGD

Real, Input---The angle, in degrees counterclockwise from the positive X axis, at which the character string is plotted.

CNTR

Real, Input---Specifies the centering option based on the following values of CNTR:

-1

The point (XPOS, YPOS) is the center of the left edge of the first character.

1.

The point (XPOS, YPOS) is the center of the right edge of the last character.

0.

The point (XPOS, YPOS) is the midpoint of the line joining the center of the left edge of the first character to the center of the right edge of the last character.

Drawing text with PLCHLQ (or PCLOQU, which has the same arguments) results in a smaller metafile than if PLCHMQ or PLCHHQ is used.

An idiosyncrasy of using PLCHLQ, PLCHMQ, and PLCHHQ is that PLCHLQ uses calls to the GKS routine GTX to draw text, whereas PLCHMQ and PLCHHQ call the GKS routines GPL and GFA. The implication is that changing text characteristics such as its color requires you to use GSTXCI for PLCHLQ and GSPLCI, and GSFACI for PLCHMQ and PLCHHQ. A better way to change character color when using PLCHHQ is to use the parameters provided for color-setting.

Line 1 of the fpcloqu.f code segment sets the color of text by specifying an index (4) in the color table that was set up previously with the GKS routine GSCR.

Line 2 chooses a font (Hershey triplex Roman) and sets the stroke precision to "best."

Line 3 plots the character string "Use" at coordinates (.41, .58) with characters that correspond to a blank size that is 4 percent of the width of the plotter frame. The string is drawn at a 55-degree angle, and (.41, .58) is the center of the string.

Line 4 plots the character string "PLCHLQ". The arguments specify a new location, size, and angle.

Real, Input---The X and Y world coordinates of the characters to be plotted.

CHRS

Character, Input---A string consisting of the characters to be plotted. CHRS may contain embedded function codes that are used to reset parameters affecting the selection of characters from the database and the way in which those characters are plotted.

The characters in CHRS are scanned from left to right and plotted. However, if a function-code signal character (a colon by default; it is defined by the parameter FC) is encountered, the following characters are interpreted as function codes until the next function-code signal character appears in CHRS. Thus if CHRS is the string 'ABC:L:DEF', then "A", "B", and "C" are treated as characters to be plotted, "L" is treated as a function code, and "D", "E", and "F" are treated as characters to be plotted. In this example, the function code "L" requests lowercase. Therefore, the string "ABCdef" would be drawn.

The function codes can take on the following values:

F, F0, Fn

Where n is a font number, selects the character database. By default, the database used is the one specified by the parameter FN. The default for FN is 0; this selects the PWRITX database. F0 returns to the PWRITX database, and F returns to the database specified by the text parameter FN.

R

Selects the Roman font when using the PWRITX database.

G

Selects the Greek font when using the PWRITX database.

P

Selects characters of principal size when using the PWRITX database.

I

Selects characters of indexical size when using the PWRITX database.

K

Selects characters of cartographic size when using the PWRITX database.

U

Selects uppercase characters when using the PWRITX database.

L

Selects lowercase characters. This affects characters from both the PWRITX and fontcap databases.

A

Draws characters across the frame.

D

Draws characters down the frame.

B

Selects a subscript level.

S

Selects a superscript level.

E

Ends subscripting or superscripting.

N

Causes a return to normal level.

Hn or HnQ

Where n is an integer, moves horizontally n digitized units or n blank widths if using HnQ.

Vn or VnQ

Where n is an integer, causes a vertical move in the same manner as Hn and HnQ.

C

Causes a return to the initial position offset by one blank height. For example, the string 'ABC:C:DEF' causes the characters "DEF" to be written directly below the characters "ABC".

Xn

Where n is an integer, causes character width to zoom to n percent of normal.

Yn

Where n is an integer, causes characters to be made n/100 times as high.

Zn

Where n is an integer, causes characters to be made n/100 times as wide and high.

CHRS

A complete description of the function codes, their meanings, and their options appears in the NCAR Graphics Programmer Document Plotchar, a Character-Plotting Package.

SIZE

Real, Input---Defines a multiplier for character size based on the following values of SIZE:

<=0.

The absolute value specifies the size as a multiple of a default digitized size on a 1024x1024 grid; blanks on this grid are 16 units wide.

0.<SIZE<1.

Specifies the desired width of a blank as a fraction of the distance across the plotter frame.

>=1

Specifies the desired width of a blank in plotter coordinates, as defined by the default or by a call to the SPPS routine SETI.

ANGD

Real, Input---The angle, in degrees counterclockwise from the positive X axis, at which the character string is plotted. The text extent or distance (in the fractional system) from the point (XPOS, YPOS) to the left, right, top, and bottom edge of a box enclosing the string can be computed by setting ANGD to 360. and the parameter TE to a nonzero value. In this case, PLCHHQ does not draw any characters; instead it stores the text extent information in the parameters DL, DR, DT, and DB. This provides a way to access this information without drawing the string.

CNTR

Real, Input---Specifies the centering option based on the following values of CNTR:

-1

The point (XPOS, YPOS) is the center of the left edge of the first character.

1.

The point (XPOS, YPOS) is the center of the right edge of the last character.

0.

The point (XPOS, YPOS) is the midpoint of the line joining the center of the left edge of the first character to the center of the right edge of the last character.

s

Where s is any real number, the point (XPOS, YPOS) is obtained by linear interpolation along the line joining the points associated with CNTR values of -1 and +1.

PLCHHQ (or PCHIQU, which has the same arguments) accesses a wider variety of fonts and controls a larger range of text characteristics than PLCHLQ or PLCHMQ. A disadvantage of using PLCHHQ, however, is that the resulting metafile tends to be larger.

Line 1 of the fpchiqu.f code segment uses the default font (principal Roman) and character database (PWRITX) to draw the text "ANGD is 45.". The text is drawn at a 45-degree angle because of the ANGD argument.

Line 2 uses function codes to draw the equation "A2+B2". The "A" is written with the default font. The ":S:" turns on one level of superscripting. The "2" is written as a superscript. ":N:" returns to the normal level. "+ B" is drawn normally. ":S:" turns on superscripting again. "2" is written as a superscript. Finally, ":N:" returns to the normal level.

Line 3 switches the function code character from a colon to a slash. Line 4 draws a text string that includes several fonts, subscripting, and superscripting.

The "/F13/" in the CHRS argument selects font 13 from the fontcap database. The characters "A line with ... fonts" is drawn in font 13. The "/F8/" selects font 8. The "P" draws the P from font 8, which is the pi symbol. "/BF13/0" turns on subscripting using font 13 and draws the character zero. The "/N/=" returns drawing to the normal level and draws an equal sign. "/F5/g" selects font 5 and draws the gamma character. The "/SF13/2" turns on superscripting, selects font 13 and then draws "2" as a superscript. The "/N/+" returns drawing to a normal level and draws the plus sign. "/F5/j" selects font 5 and draws a "j." The "/SF13/2" turns on superscripting, selects font 13 and draws a superscripted 2. Finally, the "/N/" returns drawing to the normal level.

Integer, Array---An array of color indices. Element 0 specifies the principal character color, and elements 1 through 16 specify special colors to be used for certain characters. The value -1 means "unspecified"; a value greater than or equal to 0 is a particular color index to be used. The routine PCDLSC may be called to define a standard default set of colors for elements 1 through 16. To specify element 0, use the parameter name CC(0); to access element 1, use CC(1); etc. The name CC by itself refers to element 0.

When setting the character color, use CC(0), which is the name of the first element of the parameter for character color. CC is an array of 17 elements (0-16). The first element (CC(0)) specifies the color of the principal character. Elements 1 through 16 specify special colors to be used for certain characters. Specifying CC is equivalent to specifying CC(0).

Most text characteristics are controlled using the parameter access routines discussed at the beginning of this section. In particular, text color is controlled by using PCSETI along with the parameter name CC and a color table index that specifies a red-green-blue color value.

Line 1 of the fpchiqu.f code segment sets the character color by specifying the color index 4 in the color table created previously with the GKS routine GSCR.

Lines 2 and 3 draw text using font 26.

Line 4 turns the shadow flag on. A nonzero value means that characters will be drawn with shadows.

Lines 5 and 6 set the X and Y shadow offsets, respectively. The offset is stated as a fraction of the principal character height in the direction of ANGD for X and ANGD+90 for Y.

Line 7 sets the shadow color by specifying the color table index 1.

Lines 8 and 9 draw text using font 26 and shadows.

Line 10 turns off shadows.

Line 11 turns on character outlines.

Line 12 sets the outline color by specifying the color table index 1.

Line 13 sets the outline width. The value is specified as a fraction of "normal."

The Ngmisc routine NGWSYM draws a symbol from the standard WMO/NOAA meteorological fonts by reference to the font name and symbol number within that font. This module demonstrates how to draw weather symbols using the NGWSYM routine.

Integer, Input---Specifies the number of the desired symbol within the FTYPE font.

X, Y

Real, Input---The X and Y world coordinates of the symbol position.

SIZE

Real, Input---Specifies the height of the symbol in world coordinates.

ICOLOR

Integer, Input---Specifies a GKS color index for the symbol color.

IALT

Integer, Input---Indicates whether an alternate representation for the symbol is to be used. If IALT is 1, then an alternate symbol is used. This only applies to a few symbols (such as 7, 93, 94, 95, 97 in the WW font and 3 in the W font).

The NGWSYM routine is an interface to the Plotchar utility for plotting weather symbols from fonts 36 and 37. NGWSYM looks up the appropriate symbol in either font 36 or 37 of Plotchar and uses Plotchar to draw the symbol.

The fngwsym example demonstrates how to use the NGWSYM routine to draw a weather symbol chart.

Lines 1 and 2 of the fngwsym.f code segment enter two nested loops for drawing a table of symbols. NR specifies the number of rows, and NC specifies the number of columns in the chart.

Line 3 assigns a symbol number to the NUM variable based on the current indices in the nested loops.

Line 4 draws symbol number NUM from the font specified by FONT. FONT is a character variable that contains one of the weather font character codes described previously under "FTYPE" in the argument section. The XC and YC arrays specify the position of the symbol. The fifth argument specifies a symbol size. The sixth argument, "1", specifies the GKS color index to use to color the symbol. The color table was set up prior to entering this code segment using the GKS routine GSCR. The final argument, "0", specifies not to use the alternate symbol representation.

By default, PLCHHQ draws characters from a subset of the PWRITX database called the "complex" character set; it contains 564 characters. These characters are divided into 12 groups of 47 characters specified by font (Roman or Greek), size (principal, indexical, or cartographic), and case (upper or lower).

This character set is selected by first setting the parameter CD to 0 (the default) and then selecting the PWRITX database by either using the "F" function codes as described in the PLCHHQ module or setting the parameter FN to 0 (the default).

When using the Plotchar routine PLCHHQ (or PCHIQU), the duplex character set is an alternative to using the complex character set. The duplex set has characters that are simpler than the complex set (no serifs, fewer curves, and so on.), but are still high quality. Only the alphanumeric characters differ; all other characters are the same. To access the duplex characters, reset the parameter CD to 1 and then select the PWRITX database by either using the "F" function codes as described in the PLCHHQ module or setting the parameter FN to 0 (the default).

PLCHHQ can also draw characters from databases other than the PWRITX database. The "other" databases are defined by "fontcaps." You select the fontcap databases by setting the parameter FN to n, which corresponds to fontcap n. Fontcap databases can also be selected by using the "F" function code described in the PLCHHQ module. Listed below are fontcap databases 1 through 20. These are the same fonts used with the GKS routine GTX.

Fontcap databases 21 through 137 appear below (although there are gaps in the font numbers, the databases that appear here and in the preceding modules comprise the entire set of available fonts). You select these databases in the same manner that you select fontcap databases 1 through 20. Database selection is described in the preceding module.

These fontcaps can only accessed by the Plotchar routine PLCHHQ (or PCHIQU).