DrawText

DESCRIPTION

This module creates text geometry suitable for use as titles and captions in the Render window. The module composes the text using a string plus the values of a set of input parameters. Thus, by wiring parameter values from other modules in the map to DrawText's input parameter ports, you can create captions that automatically update as these values change. The user has control over the format and precision which are used to display each numerical value, as well as control over color, font and placement for the text. The text can appear on multiple lines. In addition, you may use in-string keyword facilities as detailed below.

The placement of the text is controlled by giving the X and Y coordinates of the center of the text. If the TextGeom output from this module is wired to Render's Screen input port, these coordinates are interpreted in the screen coordinate system, where the range is -1 to +1 in both X and Y. If the output is wired to either Render's Input or Annotation port, they are interpreted in the same world space coordinate system which is used for the display of the rest of the geometry passed to Render through these ports.

INLINE KEYWORDS

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 the text string. 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, or a real number. 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
X        Start a fraction line
!        Display the current symbol

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

Note: all text between the keyword !X and the next delimiter will be interpreted as a real number; if the text does not represent a real number, then no fraction line will be drawn. The length of the fraction line is expressed in units of font size (height).

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.
A stack is utilised to keep track of the current point and character size during the plotting of any given string. Up to ten levels can be stored.
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 15.

You have a choice of 15 different fonts; these can be accessed by issuing the mnemonics (with a preceding delimiter) detailed in Table 2 (and indicated in the Fonts and Fun Fonts menus on the module's control panel).

Table 2: In-string keywords for font changing

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

01       Times-Roman                 09       Amie
02       Times-Italic                10       DJB
03       Courier                     11       Haeberli
04       Helvetica                   12       Honesty
05       Helvetica-BoldOblique       13       Inja
06       NewCenturySchlbk-BoldItalic 14       Rock
07       Palatino-Bold               25       Tymes-Elfin
08       Symbol

It may be useful to bear the following point 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.

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: Val1
Type: Parameter
Optional: This port is optional.
First input parameter value.

Port: Val2
Type: Parameter
Optional: This port is optional.
Second input parameter value.

Port: Val3
Type: Parameter
Optional: This port is optional.
Third input parameter value.

WIDGETS

Port: FontName
Type: Text
Name of the font family for the initial display of the text. Fonts are specified with PostScript names. If the specified font cannot be found (more accurately, if the geometry cannot be rendered) a warning message will appear and a suitable default font will be used in its place.

Examples of fonts are given in the Fonts pull-down menu; less serious examples can be found in the Fun Fonts menu.

Note: the specified font will be used to plot the string, until an instring keyword is used to change the font.

Port: FontSize
Type: Dial
Font size, in points.

Port: Hue
Type: Dial
Hue used to color the text. See cxHSVtoRGB for the mapping between hue values and colors - or just try turning the dial.

Port: Text
Type: Text
The input text string. Any # character in the string will be interpreted as a format code. The first occurence of # in the string will be filled in by Val1 (see above), the second will be filled in by Val2 and the third will be filled in by Val3.

In addition, the // string is interpreted as a line break. Currently the module allows a maximum of five lines in the output text. A warning message appears and the extra line breaks are ignored if the string contains more than this number of breaks.

Port: Xcoord
Type: Slider
X coordinate of center of text. Values for Xcoord and Ycoord of 0.0 will put the first line of text in the center of the Render window if the TextGeom port (see below) is connected to Render's Screen input port. Any further lines of text will be plotted centred around the same horizontal position and below the first line of text.

Port: Ycoord
Type: Slider
Y coordinate of center of text.

Port: Format1
Type: Radio Box
Menu Item: Flt
Menu Item: Exp
Format in which Val1 (see above) will appear in the text - either floating point (Flt) or exponential (Exp).

Port: Format2
Type: Radio Box
Menu Item: Flt
Menu Item: Exp
Format in which Val2 will appear in the text - either floating point (Flt) or exponential (Exp).

Port: Format3
Type: Radio Box
Menu Item: Flt
Menu Item: Exp
Format in which Val3 will appear in the text - either floating point (Flt) or exponential (Exp).

Port: Prec1
Type: Slider
Precision (number of digits following the decimal point) with which Val1 (see above) will appear in the text.

Port: Prec2
Type: Slider
Precision (number of digits following the decimal point) with which Val2 will appear in the text.

Port: Prec3
Type: Slider
Precision (number of digits following the decimal point) with which Val3 will appear in the text.

OUTPUTS

Port: TextGeom
Type: Geometry
The output geometry.

KNOWN PROBLEMS

If the text geometry is too large for the Render window when it is displayed in the Screen coordinate system, no part of it will be visible. So, if the text can't be seen in the Render window, check its placement and try decreasing the FontSize.