NAGText

DESCRIPTION

This module creates text geometry suitable for use as titles and captions in the Render window. The module plots the supplied text string in the requested font size and color at the picked position (x,y) (in screen coordinates) in the Render window. The geometry output must be wired to Render's Screen port.

NAGText is implemented using the Hershey fonts of the NAG Graphics Library. You may use all in-string keyword facilities also available to users of the NAG Graphics Library. A short description of the most important features is given in this section.

Keywords are available to support such actions as changing the current text font (perhaps to a Greek font), modifying the size and relative position of characters within the string (perhaps to draw subscripts, superscripts or mathematical expressions), etc.

Keywords may be specified as an integral part of any text string supplied to NAG Graphics [1]. Their presence will automatically be detected and the appropriate actions taken; they will not appear on the output plot. Each keyword consists of a delimiter symbol, followed by a one or two- character keyword mnemonic, which may be in upper or lower case. The keyword delimiter is an exclamation mark (`!'); As a simple example, let us take the string `E = mc!u2!N' which may be used to plot the expression E=mc². This string contains two keywords:

Keyword !u indicates that all of the following characters up to the next delimiter should be interpreted as a superscript.
Keyword !N is added to ensure that the current point is returned to the base line ready to plot any subsequent text.

The range of in-string keywords is summarised in Table 1. Where appropriate, the relative movement of the current point (up or down, in units of the current character height) and scale factor (relating to character size and spacing), are indicated.

Table 1: In-string keywords, excluding those for font changes

Mnemonic Description                      Movement  Scale Factor
----------------------------------------------------------------

A        Shift above the fraction line        1.0       1.0
B        Shift below the fraction line       -1.0       1.0
U        Move up to superscript level         0.6       0.62
D        Move down to subscript level        -0.35      0.62
E        Move to exponent level               0.94      0.44
I        Move to index level                 -0.94      0.44
L        Move to lower subscript level       -1.125     0.62
N        Move to normal or base line level    1.0

S        Save current point and character size on stack
R        Restore previous current point and character size from stack
!        Display the current symbol

Note: either upper or lower case characters may be used for the mnemonic.

In order to make effective use of the in-string keyword facility you should bear the following points in mind:

The maximum number of keyword delimiters permissible in a single string is 30.
The NAG Graphics Library utilises a stack to keep track of the current point and character size during the plotting of any given string. Up to 10 levels can be stored.
The Hershey fonts supplied as part of the NAG Graphics Library offer a wide range of symbols, including mathematical symbols, and as such it is possible to plot quite complex formulae.
Fraction lines can be plotted by selecting the Hershey Meteorological Symbol font (see Table 2) and plotting the character `X'. The length of the fraction line is determined by the number of `X's plotted.
The keyword delimiter symbol can be plotted by duplicating the delimiter symbol within the input string.
The `save' command can be used to temporarily set the `normal' line level for subsequent plotting. The new base line position is added to the stack until such time as a `restore' command is issued.

As well as giving you the opportunity to modify character positions and size, in-string keywords allow you to change the current font. This allows you, for example, to plot Greek characters as an integral part of your output text string.

The form of the in-string keyword used to select a specific font is the same as previously defined, except that the character mnemonic is replaced by a numeric value ranging from 1 to 25.

You have a choice of 25 different fonts; these can be accessed by issuing the mnemonics (with a preceding delimiter) detailed in Table 2. For ease of use, some fonts have been given a one-character mnemonic which can be used in place of the associated numeric value.

Table 2: In-string keywords for font changing

Mnemonic Description                 Mnemonic Description
---------------------------------------------------------

01       Simplex Roman               14       Cyrillic
02       Duplex  Roman               15       Triplex Roman
03       Complex Roman               16       Triplex  Italic
04 or g  Simplex Greek               17       Map  Symbols
05       Complex Greek               18       Astronomical Symbols
06       Complex Italic              19       Music Symbols
07 or m  Mathematical Symbols        20       Monospace Typewriter
08       Meteorological Symbols      21       Typewriter
09       Gothic English              22       Simplex
10 or w  Simplex Script              23       Italic
11       Complex Script              24       Complex
12       Gothic Italian              25       Complex Cyrillic
13       Gothic German

Note: either upper or lower case characters may be used for the mnemonics.

It may be useful to bear the following points in mind when using in-string keywords to change fonts:

The leading zero may be omitted for fonts 01 through 09. However, to avoid potential ambiguity, especially if numeric values follow the supplied in-string keyword, it is recommended that the leading 0 is retained. For example, the string `!11 is a number' will be plotted as ` is a number' using font style 11, whereas `!011 is a number' will give `1 is a number' plotted using font 1.
The NAG Graphics Library offers you a choice of two Greek Hershey fonts: simplex and complex. Issuing the in-string keyword mnemonic G will give you the default simplex Greek font. To select the complex font you will need to explicitly request font number 05.

References

A method for usage of a large calligraphy set under RSX-11M. Grandle, R.E. and Nystrom, P.A. Proceedings of the Digital Equipment Computer Users Society, November 1980, 391-395.

INPUTS

Port: Pick
Type: Pick
The text geometry will be centred around the x coordinate obtained by picking a point in the Render window, using the y coordinate as the baseline for the string.

In order to make the module fire, you should wire the Pick output port from the Render module to this input port, and use the Render module in User Pick mode.

WIDGETS

Port: Text String
Type: Text
Text string to be plotted

Port: Color
Type: Text
The string will be plotted in the specified color.

Port: Font Size
Type: Dial
The font size in which text will be plotted. Font size j corresponds to j * SIZE, where SIZE is two percent of the total available height of the window.

OUTPUTS

Port: Picture
Type: Geometry
Geometry generated. This port must be wired to the Screen port of the Render module in order to obtain correspondence between the point picked in the Render window, and the point around which text will be centred.

KNOWN PROBLEMS