&UGX, WHAT, WHERE

where WHAT is the name of a previously defined macro and WHERE can be used to alter the definition of the logical device to which the picture will be written. WHERE must be either: SCREEN, DEVICE, or SAVE, and if it is omitted, then the picture will be written to the primary graphics device.

A valid UGX macro is like any other macro except that it contains the commands listed below and it has the command

     END_&UGX

as its last command. For example,

     &MACRO LINE
     MOVETO 0 0
     LINE   20 20
     END_&UGX
     &ENDMACRO
     &UGX LINE

will cause a picture to appear on the screen consisting of a single line.

Several commands are available to create pictures. The origin of the coordinate system is in the upper left hand corner of the page, the x axis is parallel to the top of the page, and the y axis is parallel to the left hand side of the page. All dimensions given here are in points. To allow for a UGX picture to be correctly mapped onto any device, the command:

     BBOX, X_MAX, Y_MAX

will automatically establish a non-distorting scale so that the picture will fit on the current physical page. Here, X_MAX and Y_MAX are the maximum X and Y values which are used in the picture. Notice that by the choice of origin, there are no negative X or Y coordinates in this system.

To allow one flexibility in defining a picture, one can change the frame of reference at will by issuing the command:

     TRANSFORM, XO, YO, -OPTIONS

and the available options are:

     -SCALE, X_SCALE, Y_SCALE


     -ANGLE, ANGLE


     -MATRIX, Q11, Q21, Q12, Q22

After this command is issued, a transformation from the input coordinates to the frame described above is established which works as follows:

     o = t + Q*S*i

Where the two components of t are defined by XO and YO, the Q matrix is defined by either ANGLE or the components of Q, and the S matrix is a diagonal matrix with components given by X_SCALE and Y_SCALE. Normally, one does not need the -MATRIX option and instead defines the transformation via the -ANGLE option. Here, ANGLE is the angle in degrees through which the original x axis must be rotated to yield the new x axis. This rotation is positive toward the original y axis.

As with all output operations in MOSES, the &UGX commands are performed according to a style. To establish the current style here, one issues the command:

     STYLE, C_STYLE

Where C_STYLE is the style which will be used for all subsequent drawing. One can also change the color by issuing the command:

     COLOR, COLOR_NUM

where COLOR_NUM is a line color number. The association of line color numbers and colors was discussed previously.

Pictures are created by combining lines and text, and for each primitive, drawing begins at the "current cursor position". The current cursor position can be defined by the command:

     MOVETO, X, Y

To draw a generalized line, one issues:

     LINE, X(2), Y(2), ......, X(n), Y(n)

This command will draw n-1 straight line segments beginning at the current cursor location and ending at the coordinates X(n), Y(n). At the conclusion of the drawing, the current location will be at X(n) and Y(n). To fill a polygon in the current color, one uses:

     FILL, X(2), Y(2), ......, X(n), Y(n)

which works the same way as LINE does.

Three other primitives are available for drawing lines. To draw a rectangle, one can issue:

     BOX, X_DIM, Y_DIM

The resulting rectangle will have the upper left corner at the current location and it will have a width of X_DIM and a height of Y_DIM. At the conclusion, the current location will remain unchanged. To draw a circular arc, one issues:

     ARC, RADIUS, ANG(1), ANG(2)

The center of the arc is at the current location and the arc will have a radius of RADIUS. The arc will be drawn from the angles ANG(1) to the angle ANG(2). These angles are measured from the x axis positive toward y. If the two angles are omitted, a circle will be drawn. The current location is not changed by this command. The final line primitive draws a line with an arrow at the end of it, and is defined by:

     DLINE, X2, Y2

The line is drawn from the current location to the point X2, Y2 and the arrow is placed at the second end. At the conclusion, the current location is at X2, Y2.

Four commands are available to annotate the picture. The command:

     CSYMBOL, CSYM_NUM

will produce a "centered symbol" of a type defined by CSYM_NUM at the current location. CSYM_NUM is an integer from 1 to 9, where each number produces a different type of symbol. To write text, one has three commands available, none of which moves the current location. The command:

     TEXT, ANGLE, TXTSTR

will write the string of text defined by TXTSTR beginning at the current location. The text will be at an angle, ANGLE, from the x axis. If ANGLE is omitted, zero will be used. The current location is not effected by this command. Another way of drawing text is with the command:

     CTEXT, X2, Y2, TXTSTR

Here, the text string defined by TXTSTR is centered between the two points defined by the current location and X2, Y2. The text is drawn with the beginning of the string toward the current location so that the bottom of the text is parallel to the line between the two points. A similar command is:

     DIMENSION, X2, Y2, TXTSTR

This command draws text the same way as CTEXT, but it also draws dimension lines between the two points.

Finally, if one is merging a page in UGX into other graphics generated by MOSES with figure numbers, the UGX figure should also be numbered. This is accomplished by issuing the command:

     FIG_NUM, X, Y

which will place the figure number at the coordinates specified by X and Y.