The special version of the AGPWRT routine described earlier uses the PWRITX routine to plot the required character string. A feature of this routine is that function codes can be embedded in the character string to select different fonts, draw subscripts, etc. These function codes are the ones you will need to use if you wish to have Greek letters, etc. in your labels. The AGPWRITX documentation is given below, and is followed by a plot showing all the available characters (the Roman characters being those in the ``complex" font).
SUBROUTINE AGPWRT( XPOS, YPOS, CHRS, NCHS, ISIZ, IORI, ICEN )
This routine is a substitute for the NCAR routine of the same name, but allowing the PWRITX character drawing routine to be used instead of the usual PWRIT, giving access to special fonts, etc.
The character string accepted by the PWRITX routine includes control codes to switch font, etc. This implementation of AGPWRT accepts and passes PWRITX codes and also inserts the appropriate codes where lowercase and certain other characters are supplied. Some special characters not directly available from PWRITX are produced by means of control sequences selected through additional codes which are peculiar to this implementation of AGPWRT.
Other special values of the ICEN parameter are used to select plotting via either the PWRITX routine or the PWRIT routine. This feature allows an application to plot using GKS character drawing facilities on some occasions while using PWRITX on other occasions. The PWRITX option gives high quality characters from a rich set, but slowly; the GKS option, on the other hand, provides access to other GKS fonts and allows the use of lower text precision on graphics devices where this will reduce the plotting time.
The NCAR utilities use values of the justification argument ICEN of where left or right justification is required, and in these cases the string is plotted artificially monospaced to avoid irregular axis labelling, subject to the restriction that the string must not contain PWRITX function codes (though lowercase and common punctuation symbols are acceptable). To enable left and right justified strings to be proportionally spaced and to contain PWRITX function codes, this implementation of AGPWRT also supports the non-NCAR values ICEN . There is no provision for centred monospaced strings.
|XPOS,YPOS||r,r||string position in SPPS user coordinates|
|CHRS,NCHS||c,i||string and length, inclusive of codes, etc.|
|ICEN||i||justification, or PWRIT/PWRITX selection|
Where the special values of ICEN are used to select plotting via either PWRIT or PWRITX, the other arguments are ignored.
Displacements and character sizes are specified in ``plotter units". (N.B. Do not confuse plotter units with device coordinates. Plotter units are not related to true device resolution.) Normally the longest dimension of the display surface is 1024 plotter units. Should the resolution limitation that this implies be unacceptable, it can be changed by means of the SPPS routine SETI.
Twelve fonts are provided, each containing 47 symbols and indexed by the standard Fortran characters (A given font is specified by three letters which, in broad terms, select which combination of size (Principal, Indexical, Cartographic), alphabet (Roman, Greek), and case (upper, lower) is required.
ISIZ specifies an overall magnification factor for all the characters drawn.
Each of the three size classifications in the set of twelve fonts provided (Principal, Indexical and Cartographic) has a nominal character width (in spite of proportional spacing), height and total height. The space character is exactly one nominal width wide, and a carriage control code causes a downwards increment equal to the nominal total height, which thus includes white space.
The nominal width (W), height (H), and total height (T) for the Principal (P), Indexical (I), and Cartographic (K) fonts are as follows (plotter units):
W H T P 16 21 32 I 12 13 20 K 8 9 14
ISIZ values of 3 or less select standard magnifications of the above sizes. Values of 4 or more are proportional to the resulting magnification. The overall magnification for different ISIZ values is as follows:
ISIZ mag 8/21 1 12/21 2 18/21 3 24/21 ISIZ/21
Thus, for ISIZ3, Principal characters will be drawn nominally ISIZ plotter units high, and ISIZ can simply be thought of as the nominal character height in plotter units.
IORI is the string orientation in degrees anticlockwise from the normal left-to-right.
ICEN argument (normal use to specify positioning):
ICEN Meaning -2 (XPOS,YPOS) is the centre of the left edge of the first character. The string is proportionally spaced. -1 (XPOS,YPOS) is the centre of the left edge of the first character. The string is monospaced. Lowercase and punctuation characters are permitted, but not function codes. 0 (XPOS,YPOS) is the centre of the entire string. The string is proportionally spaced. +1 (XPOS,YPOS) is the centre of the right edge of the last character. The string is monospaced. Lowercase and punctuation characters are permitted, but not function codes. +2 (XPOS,YPOS) is the centre of the right edge of the last character. The string is proportionally spaced.
ICEN argument (special use to select string drawing routine):
ICEN Meaning -100 Selects PWRIT routine, which gives access to GKS fonts, precision, em etc. +100 Selects PWRITX routine, which gives access to special fonts and other features.
- For ICEN = the other arguments are ignored.
- Initially, PWRITX is selected.
- This inelegant use of the ICEN argument is a consequence of having to work within the standard AGPWRT call, which is made directly by the AUTOGRAPH utilities.
Characters available without using function codes:
- All uppercase and lowercase Roman characters, and most common punctuation symbols are available by including them literally in the string CHRS.
- Two consecutive apostrophes causes a single apostrophe to be drawn - for example ``
Both of these are features of this implementation of AGPWRT and are not available when directly calling PWRITX.
Function codes are sequences of characters, enclosed within apostrophes, which may (except when ICEN) be included in the character string CHRS to change font, case, etc. within the plotted string. No punctuation is needed between functions except for a comma between adjacent numbers; however, commas may be used between functions to improve readability. The following are the only legal function codes. Any other characters in a function string will be ignored except that an error report will be issued and, if more than 10 errors occur within a string, control will be returned to the main program without further plotting. At the start of the string, size, type, and case are Principal, Roman, and Upper.
R Roman characters, etc. G Greek characters, etc.
FONT SIZE (see table, above, under ISIZ)
P Principal fonts I Indexical fonts K Cartographic fonts
U or Un Upper case. If U is followed by a number n (not separated by a comma) then n characters will be drawn in uppercase and subsequent characters will be in lowercase. The U1 option is thus particularly useful for capitalizing sentences. L or Ln Lower case. If L is followed by a number n, then n characters will be drawn in lower case and subsequent characters will be in upper case.
SUBSCRIPTS AND SUPERSCRIPTS
S or Sn Superscript level. B or Bn Subscript level. N or Nn Normal level.
When switching from some ``base" character size to super- or subscripting, the character size will change depending on the base character size. Principal base characters will be subscripted or superscripted with indexical characters, with a 10 plotter unit shift (scaled in accordance with ISIZ) up or down. Indexical and cartographic base characters will be sub- or superscripted with cartographic characters with a 7 plotter unit shift.
If multiple S or B functions are used, the original base character is forgotten, and the base is simply the one preceding the latest S or B.
The case of the indexing characters will generally be the same as that of the base character unless otherwise specified. There is one exception: a lower case indexical base will be super- or subscripted with upper case cartographic, as the lowercase cartographic font is composed of special characters rather than letters and numbers.
If S, B or N is followed by a number n, then n characters will be drawn as specified above, after which character size, case and position will be reset to that of the base characters. If n is negative, its absolute value will be used instead; n cannot be zero. Do not overlap level definitions given for a specified number of characters.
The N option returns character, case and size to that of the base but maintains the current character position.
For example: 'U1'T'S1'EST will be drawn e Tst and 'U1'T'S'E'N'ST will be drawn e T st
DIRECT CONTROL OVER POSITION
Hn, HnQ Increment horizontally in the frame. Hn will shift the present X position by n plotter units. HnQ will shift the present X position by n nominal character widths. Positive n shifts to the right, and negative to the left. If n is omitted, a value of 1 is assumed. Vn, VnQ Increment vertically in the frame. Vn will shift the present Y position by n plotter units. VnQ will shift the present Y position by n nominal character total heights. Positive n shifts upwards, and negative downwards. If n is omitted, a value of 1 is assumed. H:n Increment along the direction of the string by n percent of the nominal character height for Principal characters. If n is positive the shift is rightwards, and if negative the shift is leftwards. If n is absent there is no shift. V:n Increment at right angles to the direction of the string by n percent of the nominal character height for Principal characters. If n is positive the shift is upwards, and if negative the shift is downwards. If n is absent there is no shift.
(Note: these two are nonstandard features peculiar to this implementation of AGPWRT and not available when PWRITX is called directly.)
X or Xn & Set X or Y. If the X or Y appears without a number n, the Y or Yn function will do nothing. Otherwise, the character coordinate in the X or Y direction will be set to the plotter coordinate n, so that the next character drawn will have this position in X or Y, subsequent characters will be drawn from this position.
(Note: within PWRITX, interactions with the proportional font and justification logic make these functions hard to use, and they are not recommended.)
C Carriage return: a carriage return and line feed will be done before the next character is plotted. N.B. The justification applies to the final line.
D or Dn Write down, rather than across the frame. If D appears without an n or if n=0, all characters will be written down until an `A' function is encountered. If D is followed by a number n, n characters will be written down and subsequent characters will be written across the frame. If n is negative, the absolute value of n is used instead. A Write across: escape from the D option.
.A Angstrom unit
For example, to draw a string meaning ``three Angstrom units per millimetre" we might use:
CALL AGPWRT( XPOS, YPOS, '3''.A''/mm', ...
DIRECT CHARACTER ACCESS
nnn Numeric character: character number nnn (octal) will be drawn.
Called: AGGETI, AGSETI, SETER, PWRITX, PWRIT, GTNUM, KUPX, KUPY, CPUX, CPUY
This routine uses characters outside the ANSI Fortran 77 character set.
SNX --- Starlink Extensions to the NCAR Graphics Utilities