NCL Website header
NCL Home > Documentation > Graphics

Function Codes

This 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 the default font.

How the text scanner operates

As 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 is a colon (':'), 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.

The function codes can be embedded inside any resource that produces a text string on the output device, like txString or tiMainString.

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.

Font selection

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

Carriage return

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.

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

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.