The XYOUTS procedure draws text on the currently-selected graphics device starting at the designated coordinate.
Arguments X, Y, and String can be any combination of scalars or arrays. If the arguments are arrays, multiple strings are output.
If the optional X and Y arguments are omitted, the text is positioned at the end of the most recently output text string.
Important keywords that control the appearance and positioning of the text include: ALIGNMENT, the justification of the text; CHARSIZE, the size of the text; FONT, chooses between vector drawn and hardware fonts; COLOR, the color of the text; and ORIENTATION, the angle between the baseline of the text and the horizontal. With hardware fonts, most of the text attributes, (e.g., size and orientation), are predetermined and not changeable.
| Note |
XYOUTS, [X, Y,] String [, ALIGNMENT=value{0.0 to 1.0}] [, CHARSIZE=value] [, CHARTHICK=value] [, TEXT_AXES={0 | 1 | 2 | 3 | 4 | 5}] [, WIDTH=variable]
Graphics Keywords:[, CLIP=[X0, Y0, X1, Y1]] [, COLOR=value][, /DATA | , /DEVICE | , /NORMAL] [, FONT=integer] [, ORIENTATION=ccw_degrees_from_horiz] [, /NOCLIP] [, /T3D] [, Z=value]
The horizontal and vertical coordinates used to position the string(s). X and Y are normally interpreted in data coordinates. The DEVICE and NORMAL keywords can be used to specify the coordinate units.
X and Y can be arrays of positions if String is an array.
The string(s) to be output. This argument can be a scalar string or an array of strings. If this argument is not a string, it is converted prior to use using the default formatting rules. If String is an array, X, Y, and the COLOR keyword can also be arrays so that each string can have a separate location and color.
Specifies the alignment of the text baseline. An alignment of 0.0 (the default) aligns the left edge of the text baseline with the given (x, y) coordinate. An alignment of 1.0 right-justifies the text, while 0.5 results in text centered over the point (x, y).
The overall character size for the annotation. A CHARSIZE of 1.0 is normal. Setting CHARSIZE = -1 suppresses output of the text string. This keyword has no effect when used with the hardware drawn fonts; for exceptions, see Scaled Hardware Fonts.
The line thickness of the vector drawn font characters. This keyword has no effect when used with the hardware drawn fonts; for exceptions, see Scaled Hardware Fonts. The default value is 1.0.
This keyword specifies the plane of vector drawn text when three-dimensional plotting is enabled. By default, text is drawn in the plane of the XY axes. The horizontal text direction is in the X plane, and the vertical text direction is in the Y plane. Values for this keyword can range from 0 to 5, with the following effects: 0 for XY, 1 for XZ, 2 for YZ, 3 for YX, 4 for ZX, and 5 for ZY. The notation ZY means that the horizontal direction of the text lies in the Z plane, and the vertical direction of the text is drawn in the Y plane.
Set this keyword to a named variable in which to return the width of the text string, in normalized coordinate units.
See Graphics Keywords for the description of graphics and plotting keywords not listed above. CLIP, COLOR, DATA, DEVICE, FONT, NOCLIP, NORMAL, ORIENTATION, T3D, Z.
Print the string "This is text" at device coordinate position (100,100):
XYOUTS, 100, 100, 'This is text', /DEVICE
Print an array of strings with each element of the array printed at a different location. Use larger text than in the previous example:
XYOUTS, [0, 200, 250], [200, 50, 100], $ ['This', 'is', 'text'], CHARSIZE = 3, /DEVICE
Determine the text size for a window device before opening an on-screen window:
WINDOW, /FREE, /PIXMAP, XSIZE=myWinXSize, YSIZE=myWinYSize XYOUTS, 'Check this out', WIDTH=w WDELETE
myWinXSize and myWinYSize are chosen to match your onscreen window. Since we can not know the characteristics of a given device (such as character size) until a window has been opened, the PIXMAP keyword to WINDOW allows you to compute appropriate dimensions for text with an invisible window before displaying a window on your screen.
One example of hardware fonts which can be scaled are PostScript fonts. If you are using PostScript fonts, the keywords CHARTHICK and CHARSIZE will have an effect on a call to XYOUTS. Of the devices we provide that support hardware fonts, only the PostScript device uses scalable PostScript fonts for its "hardware" font system. All other devices use a bitmapped font technology.
Scaling is related to whether or not a device supports Hershey formatting commands when hardware fonts are used. Formatting requires the ability to scale the text on a per-character basis (i.e. for subscripting). To see if a given device supports Hershey formatting when hardware fonts are used, look at bit 12 of
Introduced: Original