XGF Function Library ICR (3173)

Name

Value

NUMBER

3173

IA #

3173

DATE CREATED

2000/08/28

CUSTODIAL PACKAGE

KERNEL

CUSTODIAL ISC

San Francisco

USAGE

Supported

TYPE

Routine

DBIC APPROVAL STATUS

APPROVED

ROUTINE

XGF

NAME

XGF Function Library

GENERAL DESCRIPTION

This XGF Function Library supports terminals that are
ANSI-compatible and at least VT100-compatible. As a result, this software does
not support QUME QVT102/QVT102A terminals.

Programmer Tools > D ^XGFDEMO: Demo Program To run an interactive
demonstration showing the capabilities provided by the XGF Function Library,
you can run the XGF demo program. From the programmer prompt, type the
following: >D ^XGFDEMO <RET>

Functional Division of XGF Function Library Cursor/Text Output: IOXY^XGF,
SAY^XGF, SAYU^XGF.  Keyboard Reader: $$READ^XGF.  Setup/Cleanup: CLEAN^XGF,
INITKB^XGF, PREP^XGF, RESETKB^XGF.  Text Window: CLEAR^XGF, FRAME^XGF,
RESTORE^XGF, SAVE^XGF, WIN^XGF.  Video Attribute: CHGA^XGF, SETA^XGF.

STATUS

Active

XGF

COMPONENT/ENTRY POINT

COMPONENT DESCRIPTION

VARIABLES

CHGA

Usage D CHGA^XGF(atr_codes)

Changes individual video attributes for subsequent screen writes. Use this
entry point to change individual video attributes for subsequent output.  This
entry point is different from SETA^XGF in that individual video attributes can
be set without affecting all video attributes at once. A call to PREP^XGF must
be made at some point prior to calling CHGA^XGF. The attribute codes are not
case sensitive. You can append them if you want to set more than one
attribute. If you include more than one attribute, their order is not
important. B0 and B1 turn off and on the blink attribute; I0 and I1 turn off
and on the intensity attribute; R0 and R1 turn off and on the reverse
attribute; U0 and U1 turn off and on the underline attribute.  E1 turns off
all attributes. G0 and G1 turn off and on recognition of an alternate graphics
character set so that you can use special graphic characters, in particular
those set up by Kernel's GSET^%ZISS entry point.  To use graphics characters,
be sure you turn on graphics first (with G1) and turn graphics off afterwards
(with G0).

The change in attribute remains in effect until another CHGA^XGF, PREP^XGF or
SETA^XGF CALL is made.

VARIABLES	TYPE	VARIABLES DESCRIPTION
B1	Input	Blink on
B0	Input	Blink off
I1	Input	Intensity high
I0	Input	Intensity normal
R1	Input	Reverse video on
R0	Input	Reverse video off
G1	Input	Graphics on
G0	Input	Graphics off
U1	Input	Underline on
U0	Input	Underline off
E1	Input	Turn all off
XGCURATR	Output	This variable always holds the current screen attribute coded as a single character, and is updated when you call CHGA^XGF.

CLEAN

Use CLEAN^XGF to exit the XGF screen and keyboard
environments. It removes XGF screen and keyboard variables and tables, turns
all video attributes off, turns echo on, turns the cursor on, and sets the
keypad to numeric mode.

CLEAR

Usage D CLEAR^XGF(top,left,bottom,right)

Clears a rectangular region of the screen. This entry point is useful to clear
a portion of the screen. The CLEAR function works by printing spaces using the
current screen attribute in the specified region. If the screen attribute is
changed and then the CLEAR function used, the rectangular region is cleared in
the new attribute.

Acceptable values for the top and bottom parameters range from 0 to IOSL-1.
Acceptable values for the left and right parameters range from 0 to IOM-1.

VARIABLES	TYPE	VARIABLES DESCRIPTION
top	Input	Top screen coordinate for box
left	Input	Left screen coordinate for box
bottom	Input	Bottom screen coordinate for box
right	Input	Right screen coordinate for box.
$X,$Y	Output	Set to right and bottom specified as parameters

FRAME

Usage D FRAME^XGF(top,left,bottom,right)

Draws a box frame on the screen. Use this entry point to display boxes on the
screen. The FRAME function does not clear or otherwise change the region that
it encompasses. If you need to open an empty framed window you should use
WIN^XGF entry point instead.

Acceptable values for the top and bottom parameters range from 0 to IOSL-1.
Acceptable values for the left and right parameters range from 0 to IOM-1.E

VARIABLES	TYPE	VARIABLES DESCRIPTION
top	Input	Top screen coordinate for box.
left	Input	Left screen coordinate for box
bottom	Input	Bottom screen coordinate for box.
right	Input	Right screen coordinate for box.
$X,$Y	Output	Set to the right and bottom specified as parameters.

INITKB

Usage D INITKB^XGF([term_str])

Sets up the XGF keyboard environment only. You should call INITKB^XGF once,
before you start making calls to the $$READ^XGF function. This entry point
turns on escape processing and any terminators that are passed.  Use this
entry point only if you are using XGF's Keyboard Reader independently from
XGF's screen functions. Otherwise, a call to PREP^XGF does everything to set
up keyboard processing that INITKB^XGF does, and aseparate call to INITKB^XGF
is not necessary. Unlike PREP^XGF, INITKB^XGF does not set the keypad to
application mode. INITKB does not call %ZISS.  Thus, documented Kernel
variables such as IOKPAM and IOKPNM are not available for use without a
separate call to ENS^%ZISS.

VARIABLES	TYPE	VARIABLES DESCRIPTION
term_str	Input	String of characters that should terminate the read.

IOXY

Usage D IOXY^XGF(row,col)

Positions cursor on the screen at a screen coordinate. This entry point is
similar to Kernel's X IOXY function. The row parameter must be between 0 and
IOSL-1; the column parameter must be between 0 and IOM- 1. A call to PREP^XGF
must be made at some point prior to calling IOXY^XGF. You can specify row and
column parameters relative to the current $X and $Y by specifying "+" or "-"
to increment or decrement $X or $Y by 1. You can increment or decrement by
more than one if you add a number as well, such as "-5" or "+10". Note that
you must use quotes to pass a "+" or "-".  Otherwise, to specify exact
locations for row and column, pass numbers.

VARIABLES	TYPE	VARIABLES DESCRIPTION
row	Input	Row position to move cursor to.
col	Input	Column position to move cursor to.
$X,$Y	Output	Set to the row and column specified as parameters.

PREP

Usage D PREP^XGF

Sets up the XGF screen and keyboard environments. Before using any XGF screen
functions, you must call the PREP^XGF entry point. PREP^XGF sets up screen
control variables and tables. It also turns off all video attributes, turns
echo off, turns the cursor off, sets the keypad to application mode, and
clears the screen. In addition, PREP^XGF does everything that INITKB^XGF does
to set up the XGF keyboard environment, including turning escape processing
and terminators on. If you call PREP^XGF, a call to INITKB^XGF would be
redundant.

VARIABLES	TYPE	VARIABLES DESCRIPTION
XGCURATR	Output	One-character variable containing state of current video attribute.

$$READ

Usage S ZYXSTR=$$READ^XGF([no_of_char][,timeout])

$$READ^XGF provides a way to perform reads using escape processing. Reads,
when escape processing is turned on, are terminated by <UP-ARROW>,
<DOWN-ARROW>, <PREV>, <NEXT>, <TAB>, and other special keystrokes.  $$READ^XGF
is a low-level reader compared to the VA FileMan reader. In some respects it
is as simple as using the M read command. This read function incorporates
escape processing which puts the burden on the operating system to read the
arrow, function, and all other keys. A call to INITKB^XGF or PREP^XGF must be
made at some point prior to calling $$READ^XGF. If the number of characters
you request with the first parameter is not entered, the read does not
terminate until some terminating character is pressed (or the timeout period
is reached). If you don't pass the timeout parameter, DTIME is used for the
timeout period. If the read times out, ^ is returned and DTOUT is left
defined.

VARIABLES	TYPE	VARIABLES DESCRIPTION
no_of_char	Input	[optional] Maximum # of characters to read.
timeout	Input	[optional] Maximum duration of read, in seconds.
return_value	Output	The string read from the user. Set to the mnemonic of the key that terminated the read; see list below or the table in routine XGKB for list of possible values.
DTOUT	Output	If defined, signifies that the read timed out.

RESETKB

Usage D RESETKB^XGF

Exits the XGF keyboard environment. You should use the RESETKB^XGF call once
you finish making calls to the $$READ^XGF function. The RESETKB^XGF entry
point turns terminators and escape processing off and removes any XGF keyboard
environment variables. Subsequent reads are processed normally. Use this entry
point only if you are using XGF's Keyboard Reader independently from XGF's
screen functions. Otherwise, a call to CLEAN^XGF does everything to clean up
keyboard processing that RESETKB^XGF does, and a separate call to RESETKB^XGF
is not necessary. Unlike CLEAN^XGF, RESETKB^XGF does not set the keypad to
numeric mode.

RESTORE

Usage D RESTORE^XGF(save_root)

Use RESTORE^XGF to restore a previously saved screen region. You can save
screen regions using the WIN^XGF and SAVE^XGF entry points. RESTORE^XGF
restores the saved screen region in the same screen position as the screen
region was saved from. A call to PREP^XGF must be made at some point prior to
calling RESTORE^XGF. Specify the array node under which to save the overlaid
screen region in closed root and fully resolved form: that is, closed right
parenthesis and with variable references such as $J fully resolved. Using M
$NAME function is a quick way to pass fully resolved node specifications.

VARIABLES	TYPE	VARIABLES DESCRIPTION
save_root	Input	Global/local array node, closed root form.
$X,$Y	Output	Set to the bottom right coordinate of the restored window.

SAVE

Usage D SAVE^XGF(top,left,bottom,right,save_root)

Use this entry point to save a screen region. In order to save and restore
screen regions, you must do all screen output using calls in the XGF Function
Library output. If you instead use the M write command for output, the screen
contents cannot be saved and restored. Also, a call to PREP^XGF must be made
at some point prior to calling SAVE^XGF. Specify the array node under which to
save the overlaid screen region in closed root and fully resolved form: that
is, closed right parenthesis and with variable references such as $J fully
resolved. Using M $NAME function is a quick way to pass fully resolved node
specifications.

VARIABLES	TYPE	VARIABLES DESCRIPTION
top	Input	Top screen coordinate for box.
left	Input	Left screen coordinate for box.
bottom	Input	Bottom screen coordinate for box.
right	Input	Right screen coordinate for box.
save_root	Input	Global/local array node, closed root form.

SAY

Usage D SAY^XGF([row],[col],str[,atr])

Outputs a string to the screen (with optional positioning and
attributecontrol). Use this entry point rather than the M write command to
output strings to the screen. The row and column parameters specify where to
print the string. If omitted, the current row and column positions are used.
If specified, the row must be between 0 and IOSL-1, and the column must be
between 0 and IOM-1. A call to PREP^XGF must be made at some point prior to
calling SAY^XGF.

VARIABLES	TYPE	VARIABLES DESCRIPTION
row	Input	[optional] Row position to start write.
col	Input	String to write.
str	Input	[optional] Video attribute to write string with.
atr	Input	See CHGA^XGF for description of atr codes.
$X,$Y	Output	Set to position of the last character output.

SAYU

Usage D SAYU^XGF([row],[col],str[,atr])

Outputs a string to the screen (with optional position and attribute control),
including the ability to underline an individual character. This entry point
is similar to SAY^XGF. The difference is that the first ampersand ("&")
character has a special meaning in the output string; it acts as a flag to
indicate that the next character should be underlined.  You are only allowed
one underlined character per call. Typically you would use SAYU^XGF when
writing a menu option's text, in order to underline that option's speed key.A
call to PREP^XGF must be made at some point prior to calling SAYU^XGF.

VARIABLES	TYPE	VARIABLES DESCRIPTION
row	Input	[optional] Row position to start write.
col	Input	[optional] Column position to start write.
str	Input	String to write ("&" underlines next character).
atr	Input	[optional] Video attribute to write string with (see CHGA^XGF for description of atr codes).
$X,$Y	Output	Set to the position of the last character output.

SETA

Usage D SETA^XGF(atr_code)

SETA^XGF sets all video attribute simultaneously, for subsequent screen
output. This entry point is different from CHGA^XGF in that it takes a
different form of the attribute argument, and, unlike CHGA^XGF, sets all
attributes. The change in attribute remains in effect until you make another
CHGA^XGF, CLEAN^XGF or SETA^XGF call. If you want only a temporary change in
attribute, SAY^XGF may be a better function to use. A call to PREP^XGF must be
made at some point prior to calling SETA^XGF. The value of the attribute
parameter uses one bit for the value of each video attribute. The format of
the bits is not documented. The current setting of all video attributes is
accessible via the variable XGCURATR, however.  Rather than trying to use
SETA^XGF to control an individual video attribute's setting, you should use it
mainly to restore the screen attributes based on a previously saved value of
XGCURATR.

VARIABLES

TYPE

VARIABLES DESCRIPTION

atr_code

Input

Single character containing the states of all video
attributes as the bit values. This argument itself should be derived from a
previous call to PREP^XGF, CHGA^XGF, or SETA^XGF.

XGCURATR

Output

This variable always holds the current screen
attribute coded as a single character, and is updated when you call SETA^XGF.

WIN

Usage D WIN^XGF(top,left,bottom,right[,save_root])

Use this entry point to open a text window on the screen and optionally
remember what it overlays. If the save root parameter is not passed, you
cannot restore the screen behind the window. In order to save the screen
region that the window overlays it is absolutely necessary that screen output
is done using only the functions in the XGF Function library. If you use the M
write command for output, the screen contents cannot be saved. A call to
PREP^XGF must be made at some point prior to calling WIN^XGF. Specify the
array node under which to save the overlaid screen region in closed root and
fully resolved form: that is, closed right parenthesis and with variable
references such as $J fully resolved. Using M $NAME function is a quick way to
pass fully resolved node specifications. To restore screens you save with the
WIN^XGF function, use the RESTORE^XGF entry point.

VARIABLES	TYPE	VARIABLES DESCRIPTION
top	Input	Top screen coordinate for box.
left	Input	Left screen coordinate for box.
bottom	Input	Bottom screen coordinate for box.
right	Input	Right screen coordinate for box.
save_root	Both	[optional] Global/local array node, closed root form.
$X,$Y	Output	If you specify a node as a fifth parameter for save_root, WIN^XGF saves the screen region you overlay in an array at that node. Set to the right and bottom coordinates you specify as parameters.