Function codesThis page describes the syntax and capabilities of function codes that you can embed within a string to select the font, change to superscript or subscript, and add vertical or horizontal spacing. There are other function codes as well, but they apply only to font 0.
How the text scanner operatesAs the characters of a string are scanned from left to right, the scanner is always in one of two states: either it is looking for characters to be drawn, or it is looking for characters to be interpreted as function codes. The default function code for PyNGL is a tilde ('~'), and each occurrence of the function-code signal character flips the state of the scanner.
For example, if you have the string "ABC~L~DEF", 'A', 'B', and 'C' will be treated as characters to be drawn, 'L' will be treated as a function code (in this case, it would draw the following characters in lower case), and 'D', 'E', and 'F' will be treated as characters to be drawn.
The default function code can be changed by adding the following line to your .hluresfile:
*TextFuncCode : ~The above changes the function code to a tilde ('~') for all string resources. If you just want to change the function code for a particular string resource, like tiXAxisString, then use the corresponding FuncCode resource for that string resource: tiXAxisFuncCode.
No punctuation is needed between function codes except for a comma or a blank between adjacent numbers. However, extra commas and blanks may be used to improve readability. The function codes described below are the only legal ones, any other characters in a function code string will be ignored, and an error message will be printed.
- F or F0 or Fn, where n is one of the legal font numbers.
Font definitionsThese function codes affect the selection of characters from the pwritx_database font:
- R selects the Roman font.
- G selects the Greek font.
Size definitionsThese function codes affect the selection of character size and style when pwritx_database font is used and only the size when any other font is used.
- P selects characters of principal size.
- I selects characters of indexical size.
- K selects characters of cartographic size.
~F16K~ABC", the characters drawn will be those defined by font 16 (gothic_english) corresponding to the uppercase characters 'A','B', and 'C', but they will be reduced in size to approximately match the size of the cartographic characters from the pwritx_database font.
Case definitionsThese function codes affect the selection of characters from the pwritx_database font. (An "L" function code will also affect the selection of characters from the other fonts. For example, if txString is set to "
~F16L~ABC", the characters drawn will be those defined by font 16 (gothic_english) corresponding to the lowercase characters 'a', 'b', and 'c'.)
- U or Un selects uppercase.
- L or Ln selects lowercase.
If L is followed by a number n, then n characters will be drawn in lowercase, and subsequent characters will be in uppercase.
Direction definitionsThese function codes determine where each character is placed relative to the previous one:
- A causes characters to be written "across" the frame.
- D or Dn causes characters to be written "down" the frame.
If D appears without a following integer n or if n is zero, characters will be written "down" until an 'A' is encountered. If n appears, n characters will be written "down" and subsequent characters will be written "across" the frame.
The terms "across" and "down" are to be interpreted to mean "in the direction txAngleF" and "in the direction txAngleF - 90", respectively. Each character has a left edge center point, a right edge center point, a bottom edge center point, and a top edge center point, as defined by information in the database of the font from which it came. These points are not necessarily on the actual edges of the character, but on the edges of a rectangle containing the character; the points are also not necessarily exactly centered on the edges of the rectangle. Characters are always oriented so that the vector from the left edge center point to the right edge center point is in the direction txAngleF. When characters are written across the frame (assuming that the constant spacing parameter txConstantSpacingF is zero), each character is placed so that its left edge center point is coincident with the right edge center point of the previous character. Similarly, when characters are being written down the frame, each character is placed so that its top edge center point is coincident with the bottom edge center point of the previous character.
Level definitionsThese function codes determine the level on which characters are to be written:
- B or Bn selects subscript level.
- S or Sn selects superscript level.
- E means "end of subscripting or superscripting".
- N causes a return to normal level.
~S3~A~B2~BC", in which the three-character count for superscripting is not satisfied at the time the two-character count for subscripting is seen).
The function code E terminates the current level of subscripting or superscripting, restoring the size, case, and position to that of the base character. The function code N terminates the current level of subscripting or superscripting, restoring the size and case to that of the base character, but the position as required to continue writing at the level of the base character without writing over the subscripts or superscripts.
Examples:See ngl10p.py and its output.
- To write "10 to the 10 to the 100", use the string
10~S~10~S~100". Up to five levels are allowed.
- To write "X sub 2, cubed", use the string
X~B1~2~S1~3". Note that when the character count in the "B1" is satisfied, the original base character is reinstated, so that we can add another subscript or superscript to it.
- To write "X sub 2, cubed, times Y cubed", use the string
X~B1~2~S~3~N~Y~S~3". The function code N returns to normal level in such a way that the character Y does not overwrite the 2 and the 3.
- To write "X to the power A sub 1", followed by "something else",
use the string "
X~S~A~B~1~NN~something else". Note that two function code N's are used, one to terminate writing the subscript 1 and another to terminate writing the superscript "a sub 1" and leave the current position such that what follows won't go on top of the "a sub 1".
Coordinate definitionsThese function codes adjust the current position, so that the next character will be drawn offset from the position it would otherwise have had:
- Hn or HnQ causes a "horizontal" move.
- Vn or VnQ causes a "vertical" move.
- C causes a "carriage return" before the next character is drawn.
A Vn or VnQ increments the current position in the direction specified by txAngleF + 90. Vn shifts the position by n digitization units and VnQ shifts the position by n blank heights; in either case, n can be negative.
A C causes a return to either the initial position, if there have
been no other C function codes, or to the position following the last
occurrence of a C function code, otherwise. The position is then
offset by one blank height in the direction txAngleF -90. For example, the string
ABC~C~DEF" causes the characters ABC to be written and
ten causes the characters DEF to be written directly under the ABC.
Character zoomingThese function codes may be used to alter the aspect ratio of subsequent characters:
- Xn or XnQ causes character width to zoom to "n" percent of normal.
- Yn or YnQ causes character height to zoom to "n" percent of normal.
- Zn or ZnQ causes character width and height to zoom to "n" percent of normal.
Using Yn or YnQ will cause subsequent characters to be made n/100 times as high (zoomed in the direction txAngleF + 90). A suffixed Q will cause a shift of character position in the direction txAngleF + 90 sufficient to keep the bases of the characters properly aligned. If "n" is omitted or zero, 100 is assumed.
Using Zn or ZnQ will cause subsequent characters to be made n/100 times as wide and high (zoomed in both of the directions txAngleF and txAngleF + 90). A suffixed Q will cause a shift of character position in the direction txAngleF + 90 sufficient to keep the bases of the characters properly aligned. If "n" is omitted or zero, 100 is assumed.
Direct character accessOctal numbers may be used as function codes to select particular characters from the pwritx_database font. The octal number for a given character is the sum of a font index (0 for Roman or 600 for Greek), a size index (0 for Principal, 200 for Indexical, or 400 for Cartographic), a case index (0 for Upper or 100 for Lower), and the octal equivalent of a character index (1-32 for A through Z, 33-44 for 0 through 9, or 45-57 for the individual characters +, -, *, /, (, ), $, =, blank, comma, and period). For example, the string "
~GIU~*" is the same as the string "
~1047~" (600+200+0+47=1047, octal.) To find the character produced for a given octal code, refer to the plots produced by the low-level NCAR Graphics example "epltch".
Note: In the "epltch" example (see previous paragraph), you can
write two of the characters in a row by using either the string
'~GIU~**' or the string "
~1047,1047~". This is one
example of the need for a comma between two function codes.
An octal number may be used as a function code in part of the input character string during the processing of which characters are being selected from fonts other than the pwritx_database font. Such an octal function code will still have the effect of selecting a character from the pwritx_database font.