Text function codes

Description

This page describes the syntax and capabilities of function codes that you can embed within a TextItem string. It is a slightly modified version of the description of function codes in the Programmer's Document for the low-level NCAR Graphics utility Plotchar. You will need to understand function codes in order to modify the TextItem object string for any of the following purposes:

To select characters from fonts other than the "normal" font that is set using the resource txFont.
To select the "level" on which characters are to be written: superscript level, subscript level, or normal level. Subscripting and superscripting may be carried to as many as five levels, as in "A to the B to the C to the D to the E to the F". Changing level usually also changes font, case, and size (if using the pwritx_database font) or just size (if using any of the other fonts), but all such changes may be overridden by function codes forcing the desired values.)
To take complete control of the positioning of characters relative to one another, including the creation of multi-line TextItem object strings through the use of embedded "carriage returns".
To specify individual characters from the pwritx_database font, using octal numbers as function codes.
To "zoom" characters in either width or height, or both.

How the text scanner operates

As the characters of txString 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. As the scan begins, the scanner is looking for characters to be drawn. Each occurrence of the function-code signal character (specified using the txFuncCode resource--a colon by default) flips the state of the scanner. Thus, if txString were set to "ABC:L:DEF", 'A', 'B', and 'C' will be treated as characters to be drawn, 'L' will be treated as a function-code character, and 'D', 'E', and 'F' will be treated as characters to be drawn. (In this particular example, since the function code 'L' requests lower case, what would be drawn is the string "ABCdef".)

An example of a string containing function codes is as follows:

:PRU:A:S:2:N:+B:S:2:N:

This might be read by a knowledgeable user as "Principal Roman Upper A, Superscript level, 2, Normal level, plus B, Superscript level, 2, Normal level" and it writes the equivalent of "A squared plus B squared". Because of the way the colons are paired, the characters 'P', 'R', 'U', 'S', 'N', 'S', and 'N' are function codes; all other characters are characters to be written.

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, but an error message will be printed.

Font selection

Use these function codes to change the font:

F or F0 or Fn, where n is one of the legal font numbers.

The default at the beginning of a string is to use the font implied by the resource txFont. (By default, txFont is set to zero, selecting the pwritx_database font.) The function code 'F', without a following integer, implies a return to the font specified by the txFont resource.

Font definitions

These function codes affect the selection of characters from the pwritx_database font:

R selects the Roman font.
G selects the Greek font.

The default at the beginning of a string is to use the Roman font.

Size definitions

These 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.

The default at the beginning of a string is to use characters of principal size. When you use the pwritx_database font, these function codes affect the style of the character as well as its size. That is because the pwritx_database font is in reality a concatenation of several different fonts. However, when other fonts are used, these codes actually do just affect the size of the character. For example, if txString is ":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 definitions

These 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 U is followed by a number n (with no intervening comma), then n characters will be drawn in uppercase, and subsequent characters will be in lowercase. (The Un option is particularly useful for capitalizing sentences.)

If L is followed by a number n, then n characters will be drawn in lowercase, and subsequent characters will be in uppercase.

The default at the beginning of a string is uppercase.

Direction definitions

These 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.

The default at the beginning of a string is to write across 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 definitions

These 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.

If S or B is followed by a positive integer n, then n characters will be drawn as specified above, after which size, case and position will be reset to that of the base character. Do not overlap level definitions given for a specified number of characters (as, for example, in the string ":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:

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 definitions

These 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.

An Hn or HnQ increments the current position in the direction specified by txAngleF. Hn shifts the position by n digitization units and HnQ shifts the position by n blank widths; in either case, n can be negative.

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 zooming

These 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 Xn or XnQ will cause subsequent characters to be made n/100 times as wide (zoomed in the direction txAngleF). A suffixed Q is ignored. If "n" is omitted or zero, 100 is assumed.

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 access

Octal 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.

Reference Manual Control Panel

NG4.1 Home, Index, Examples, Glossary, Feedback, Ref Contents, Ref WhereAmI?

$Revision: 1.5 $ $Date: 1998/06/15 21:25:53 $