@(x, y) Function |
![]() ![]() ![]() |
The @(x, y) function is used to control the format of displayed output.
Format
where
The @(x, y) functions return string values which can be used in the same way as any other strings. They only take effect when the string is used in a CRT, DISPLAY or PRINT statements directed to the display. The actual value returned by the function is a control code to be sent to the terminal and is dependant on the type of terminal in use (see the TERM command).
When output is directed to a printer or to a file for later printing rather than to the display, escape sequences relevant to the printer may be used for formatting, etc. Because the @(x,y) function returns codes specific for the terminal in use, it is unlikely that these codes are relevant for printers.
Cursor Positioning
The @(col {, line}) format specifies that subsequent output is to appear at the given column and, optionally, line position. Columns and lines are numbered from zero where the top left of the screen is line 0, column 0. The effect of attempting to move to a cursor position outside the display area is undefined.
Use of the @(col {, line}) function disables screen pagination (automatic display of the "Press return to continue" prompt after each screen of output). Pagination remains disabled until the program executes the PRINTER RESET statement or return to the command prompt.
Use of the EXECUTE statement enables screen pagination, executes the command(s) and then restores pagination to its state when the EXECUTE was performed.
Special Functions
@(x, y) functions with negative values of x are used to provide a variety of control functions. These are largely in common with the functions defined for other systems. The token names shown in the table below are defined in the KEYS.H include record in the SYSCOM file.
Functions not supported by the terminal device in use return a null string and hence will be ignored. Note that individual terminal types may place restrictions on use of display attributes such as flashing, underline, colour, etc. For example, although each attribute has a corresponding start and end control code pair, many terminals can only apply a single attribute to any particular screen region.
Display attributes are also implemented in two fundamentally distinct ways. Most modern terminals maintain an attribute for each character position on the display and data is stored by the terminal using the currently active attributes regardless of any intervening cursor movements. On some other terminals, the code sent by an @() function to set or clear an attribute occupies a character position on the screen. Starting at the top left of the screen and working row by row through each character position, the attributes of any particular character are determined by the most recent attribute setting encountered.
For example, DISPLAY @(-1):@(-15):'ABC':@(-16):'DEF' on a terminal that stores the attribute for each character position would result in a display of ABCDEF whereas a terminal that uses a character cell to store the attribute would display ABC DEF
Furthermore, if the program then executed DISPLAY @(3,0):'X' the first terminal would display ABCXEF but the second would display ABCXDEF with the underline extending to the end of the screen or the next cell holding an attribute setting.
Descriptions
IT$CS (Clear screen) The screen is cleared to the current background colour. The cursor is positioned at the top left of the screen (position 0,0).
IT$CAH (Cursor home) The cursor is positioned at the top left of the screen (position 0,0).
IT$CLEOS (Clear to end of screen) All screen positions between the current cursor position and the end of the screen are cleared. Some terminal devices/emulators set the cleared character positions to have the current background colour.
IT$CLEOL (Clear to end of line) All screen positions between the current cursor position and the end of the line are cleared. Some terminal devices/emulators set the cleared character positions to have the current background colour.
IT$CUB (Backspace) The cursor moves left by the number of positions specified in the second argument which defaults to one or until the left edge of the screen is reached.
IT$CUU (Cursor up) The cursor moves up by the number of lines specified in the second argument which defaults to one or until the top line of the screen is reached.
IT$SHALF (Start half brightness) Displays subsequent data in half brightness (dim) mode.
IT$EHALF (End half brightness) Terminates half brightness (dim) mode.
IT$SREV (Start reverse video) If not already in reverse video mode, the foreground and background colours are interchanged for subsequent output. Selecting this mode does not directly affect any data which is already displayed.
IT$EREV (End reverse video) If in reverse video mode, this operation reverts to the normal display colours for subsequent text output.
IT$IL (Insert line) The number of lines specified in the second argument (default value one) are inserted at the current cursor position. Data at the bottom of the screen will be lost. The newly inserted lines are set to the background colour.
IT$DL (Delete line) The number of lines specified in the second argument (default value one) are deleted at the current cursor position. Blank lines are inserted at the bottom of the screen.
IT$ICH (Insert character) The number of characters specified in the second argument (default value one) are inserted at the current cursor position. Data at the right of the screen will be lost.
IT$DCH (Delete character) The number of characters specified in the second argument (default value one) are deleted at the current cursor position. Blanks are inserted at the right edge of the screen.
IT$AUXON (Turn on printer) For terminals with attached printers, this mode directs output to the printer. The mc5 terminfo entry must be set correctly for this to work.
IT$AUXOFF (Turn off printer) For terminals with attached printers, this mode turns off output to the printer. The mc4 terminfo entry must be set correctly for this to work.
IT$E80 (Set 80 column mode) The display window is set to be 80 characters wide.
IT$E132 (Set 132 column mode) The display window is set to be 132 characters wide.
IT$RIC (Reset inhibit cursor) The cursor is displayed if it was previously inhibited.
IT$SIC (Inhibit cursor) Display of the cursor is inhibited. All cursor positioning functions continue to work whilst the cursor is not visible.
IT$CUD (Cursor down) The cursor moves down by the number of lines specified in the second argument which defaults to one or until the bottom line of the screen is reached.
IT$CUF (Cursor forward) The cursor moves right by the number of positions specified in the second argument which defaults to one or until the right edge of the screen is reached.
IT$FGC (Set foreground colour) The foreground colour is set according to the value of the second argument. This may be set using the tokens listed below from the KEYS.H record of the SYSCOM file.
Some terminal emulators provide the ability to map these colour values to an alternative colour palette. The terminfo COLOURMAP setting can be used to translate the internal QM values listed above to an alternative set relevant to a specific terminal emulator.
IT$BGC (Set background colour) The background colour is set according to the value of the second argument. This may be set using the tokens from the KEYS.H record of the SYSCOM file as listed above.
IT$SLC (Set line truncation) With this mode enabled, the cursor does not automatically move to a new line when data is displayed in the final column of the screen. Any further output on the line will overwrite the final character.
IT$RLT (Reset line truncation) Clears line truncation mode so that the cursor automatically moves to a new line when data is displayed in the final column of the screen.
IT$ACMD (Asynchronous command) Executes the given command on the client system without suspending the QM session. This operation depends on correct setting of the terminfo u8 token.
IT$SCMD (Synchronous command) Executes the given command on the client system, suspending the QM session until the command completes. This operation depends on correct setting of the terminfo u9 token.
IT$STYLUS (Enable/disable stylus taps) Applicable only to QM on a PDA, this operation allows an application to receive stylus taps via input operations. When enabled, a stylus tap appears as char(200) (K$MOUSE) followed by the column and row coordinates separated by a comma and terminated with a carriage return. Set the second argument to a non-zero value to enable stylus taps, zero to disable them. Stylus input is disabled by default when QM starts.
IT$KEYS (Display/hide screen keyboard) Applicable only to QM on a PDA, this operation displays or hides the on screen keyboard. Set the second argument to a non-zero value to show the keyboard, zero to hide it.
Examples
DISPLAY @(IT$CS) : @(34,10) : "Please wait" :
This statement clears the screen and displays "Please wait" .
DISPLAY @(IT$FGC, IT$BRIGHT.RED) : "Error " : STATUS()
This statement displays the value of the STATUS() function in bright red. Further output to the display will continue to be in this colour until the foreground colour is reset.
|