13.22. TERMINAL/IO

About
Functions order

13.22.1. About TERMINAL/IO

13.22.2. TERMINAL/IO functions order

ACHOICE() Execute a pop-up menu
ALERT() Display a simple modal dialog box
COL() Return the screen cursor column position
COLORSELECT() Activate attribute in current color settings
DEVOUT() Write a value to the current device
DEVOUTPICT() Write a value to the current device using a picture clause
DEVPOS() Move the cursor or printhead to a new position depending on the current
DISPBEGIN() Begin buffering screen output
DISPBOX() Display a box on the screen
DISPCOUNT() Return the number of pending DISPEND() requests
DISPEND() Display buffered screen updates
DISPOUT() Write a value to the display
GETACTIVE() Return the currently active Get object
GETAPPLYKEY() Apply a key to a Get object from within a reader
GETDOSETKEY() Process SET KEY during GET editing
GETPOSTVALIDATE() Postvalidate the current Get object
GETPREVALIDATE() Prevalidate a Get object
GETREADER() Execute standard READ behavior for a Get object
ISCOLOR() Determine if the current computer has color capability
ISPRINTER() Determine whether LPT1 is ready
MAXCOL() Determine the maximum visible screen column
MAXROW() Determine the maximum visible screen row
MENUMODAL() Activate a top bar menu
NOSNOW() Toggle snow suppression
OUTERR() Write a list of values to the standard error device
OUTSTD() Write a list of values to the standard output device
PCOL() Return the current column position of the printhead
PROW() Return the current row position of the printhead
QOUT() Display a list of expressions to the console
READEXIT() Toggle Up arrow and Down arrow as READ exit keys
READFORMAT() Return and optionally, set the code block that implements a format (.fmt)
READINSERT() Toggle the current insert mode for READ and MEMOEDIT()
READKEY() Determine what key terminated a READ
READKILL() Return, and optionally set, whether the current READ should be exited
READMODAL() Activate a full-screen editing mode for a GetList
READUPDATED() Determine whether any GET variables changed during a READ and optionally
READVAR() Return the current GET/MENU variable name
RESTSCREEN() Display a saved screen region to a specified location
ROW() Return the screen row position of the cursor
SAVESCREEN() Save a screen region for later display
SCROLL() Scroll a screen region up or down, right or left
SETBLINK() Toggle asterisk (*) interpretation in the SETCOLOR() string between blinking
SETCANCEL() Toggle Alt+C or Ctrl+C and Ctrl+Break as program termination keys
SETCOLOR() Return the current colors and optionally set new colors
SETCURSOR() Set the cursor shape
SETKEY() Assign an action block to a key
SETMODE() Change display mode to a specified number of rows and columns
SETPOS() Move the cursor to a new position
SETPRC() Set PROW() and PCOL() values
TONE() Sound a speaker tone for a specified frequency and duration
UPDATED() Determine whether a GET changed during a READ

13.22.2.1. Function COL()

 COL() --> nCol

13.22.2.2. Function COLORSELECT()

 COLORSELECT(<nColorIndex>) --> NIL

13.22.2.4. Function DEVOUTPICT()

 DEVOUTPICT(<exp>, <cPicture>, [<cColorString>]) --> NIL

13.22.2.5. Function DEVPOS()

 DEVPOS(<nRow>, <nCol>) --> NIL

13.22.2.5.3. Description

DEVPOS() is an environment function that moves the screen or printhead depending on the current DEVICE. If DEVICE is SET to SCREEN, DEVPOS() behaves like SETPOS(), moves the cursor to the specified location, and updates ROW() and COL() with the new cursor position.

If DEVICE is SET to PRINTER, DEVPOS() moves the printhead instead. It does this by sending the number of linefeed and/or formfeed characters to the printer, and advancing the printhead to the new position. If the current SET MARGIN value is greater than zero, it is added to <nCol>. The printhead is then advanced to the specified <nRow> and <nCol> position and PROW() and PCOL() are updated. If either <nRow> or <nCol> are less than the current PROW() and PCOL() values, the printhead is moved according to the following special rules:

If <nRow> is less than PROW(), an automatic EJECT (CHR(12)) is sent to the printer followed by the number of linefeed characters (CHR(10)) required to position the printhead on <nRow> of the following page.

If <nCol> including the current SET MARGIN value is less than PCOL(), a carriage return character (CHR(13)) and the number of space characters required to position the printhead at <nCol> are sent to the printer.

To circumvent these rules, use SETPRC() to reset PROW() and PCOL() to new values before using DEVPOS(). See the SETPRC() discussion for more information.

If the printer is redirected to a file using the SET PRINTER command, DEVPOS() updates the file instead of the printer.

13.22.2.7. Function DISPBOX()

 DISPBOX(<nTop>, <nLeft>, <nBottom>, <nRight>,
 [<cnBoxString>], [<cColorString>]) --> NIL

13.22.2.7.3. Description

DISPBOX() is a screen function that draws a box at the specified display coordinates in the specified color. If you specify <cnBoxString>, DISPBOX() draws a box on the screen using configurable border and fill characters. DISPBOX() draws the box using <cnBoxString> starting from the upper left-hand corner, proceeding clockwise and filling the screen region with the ninth character. If the ninth character is not specified, the screen region within the box is not painted. Existing text and color remain unchanged.

In cases where cnBoxString respects xClipper conventions, the behavior of DISPBOX() is unchanged. The behavior of this function can easily be modified to take advantage of graphic mode. For example, you can replace the standard window frames using single or double lines with new graphical frames that have an impressive 3-D look. Simply replace the cBoxString parameter using the following:

CHR(2) + CHR(nColor+1) // draws a box of thickness 16x8x16x8 CHR(3) + CHR(nColor+1) // draws a box of thickness 8x8x8x8 CHR(4) + CHR(nColor+1) // draws a box of thickness

// 16x16x16x16 CHR(5) + CHR(nColor+1) // draws a box of thickness 16x8x8x8

Note that <nColor> is a numeric color representation. You must add 1 to this value.

In general, CHR(2) + CHR(nColor+1) can be used instead of xClipper's B_SINGLE or B_DOUBLE defines.

xClipper graphics comes with two #defines LLG_BOX_GRAY_STD and LLG_BOX_GRAY_SQUARE to allow gray (nColor=7) boxes of width 16x8 or 16x16.

You can completely customize the box by passing chr(1) + ... as the first parameter:

CHR(1) + ; // Box entirely defined CHR(nBackColor+1) + ; // Color used as background fill CHR(nLightColor+1) + ; // Color used to lighten the frame CHR(nDarkColor+1) + ; // Color used to darken the frame CHR(nWidthUp) + ; // Thickness of upper edge of box CHR(nWidthRight) + ; // Thickness of right edge of box CHR(nWidthDown) + ; // Thickness of lower edge of box CHR(nWidthLeft) // Thickness of left edge of box

After DISPBOX() executes, the cursor is located in the upper corner of the boxed region at <nTop> + 1 and <nLeft> + 1. ROW() and COL() are also updated to reflect the new cursor position.

Note that Box.ch, located in \include, provides constants for various border configurations.

13.22.2.10. Function DISPOUT()

 DISPOUT(<exp>, [<cColorString>]) --> NIL

13.22.2.16. Function GETREADER()

 GETREADER(<oGet>, <GetList>, <oMenu>, <nMsgRow>,
 <nMsgLeft>, <nMsgRight>, <cMsgColor>) --> NIL

13.22.2.21. Function MENUMODAL()

 MENUMODAL(<oTopBar>, <nSelection>, <nMsgRow>,
 <nMsgLeft>, <nMsgRight>, <cMsgColor>) --> MenuID

13.22.2.21.3. Description

MENUMODAL() is a user-interface function that implements the pull-down menu system in xClipper. It is part of the open architecture Get system of xClipper. MENUMODAL() is similar to the READ command in that it waits for the user to perform an action. However, the MENUMODAL() function will only respond to menu actions.

To implement a menu object at the same time as other objects, use the READMODAL() function which has one of its arguments as TopBarMenu object.

When the user chooses a menu item, control is passed to the code block associated with that particular menu item. Code blocks are defined using the MenuItem class.

The menu items can be selected by using either the keyboard or the mouse. To select a menu item with the mouse, simply select its TopBarMenu item with the mouse and then choose the appropriate PopUp menu item.

Note: The MENUMODAL() function will take one menu event from the user and then terminate. To avoid this, the following can be used, and the same will allow the program to continuously accept menu events:

DO WHILE (MENUMODAL(themenu,...) <> ExitMenu) ENDDO

The following table lists the active keys that can be used during MENUMODAL():

 MENUMODAL() Navigation Keys
 ------------------------------------------------------------------------
 Key                 Action
 ------------------------------------------------------------------------
 Left arrow, Ctrl+S  Move to the next TopBarMenu item to the left.  If
 there are no more items to the left, the rightmost
 TopBarMenu item will be selected.
 Right arrow, Ctrl+D Move to the next TopBarMenu item to the right.  If
 there are no more items to the right, the leftmost
 TopBarMenu will be selected.
 Up arrow, Ctrl+E    Move to the previous PopUp menu item.  If there are
 no more items above the current item, the menu item
 on the bottom will be selected.
 Down arrow, Ctrl+X  Move to the next PopUp menu item.  If there are no
 more items below the current item, the menu item on
 the top will be selected.
 ------------------------------------------------------------------------
 

13.22.2.23. Function PCOL()

 PCOL() --> nColumn

13.22.2.24. Function PROW()

 PROW() --> nRow

13.22.2.27. Function READINSERT()

 READINSERT([<lToggle>]) --> lCurrentMode

13.22.2.28. Function READKEY()

 READKEY() --> nReadkeyCode

13.22.2.30. Function READMODAL()

 READMODAL(<aGetList>, [<nGet>], [<oMenu>], [<nMsgRow>,
 <nMsgLeft>, <nMsgRight>, <cMsgColor>])
 --> <lUpdated>

13.22.2.30.3. Description

READMODAL() is a user interface function that implements the full-screen editing mode for GETs, and is part of the open architecture Get system of xClipper. READMODAL() is like the READ command, but takes a GetList array as an argument and does not reinitialize the GetList array when it terminates. Because of this, you can maintain multiple lists of Get objects and activate them any time in a program's execution as long as the array to activate is visible.

In order to retain compatibility with previous versions of xClipper, the GET system in xClipper is implemented using a public array called GetList. Each time an @...GET command executes, it creates a Get object and adds to the currently visible GetList array. The standard READ command is preprocessed into a call to READMODAL() using the GetList array as its argument. If the SAVE clause is not specified, the variable GetList is assigned an empty array after the READMODAL() function terminates.

Some of the functions in the Getsys.prg have been made public so that they can be used when implementing customized GET readers. These functions are listed in the table below.

 Get System functions
 ------------------------------------------------------------------------
 Function            Description
 ------------------------------------------------------------------------
 GETACTIVE()         Return the currently active Get object
 GETAPPLYKEY()       Apply a key to a Get object from within a GET reader
 GETDOSETKEY()       Process SET KEY during GET editing
 GETPOSTVALIDATE()   Postvalidate the current Get object
 GETPREVALIDATE()    Prevalidate a Get object
 GETREADER()         Execute standard READ behavior for a Get object
 READFORMAT()        Return and, optionally, set the code block that
 implements a format (.fmt) file
 READKILL()          Return and, optionally, set whether the current Read
 should be exited
 READUPDATED()       Return and, optionally, set whether a GET has
 changed during a Read
 ------------------------------------------------------------------------
 

For reference information on the Get objects and functions listed above, refer to the "Get System" chapter in the Programming and Utilities Guide.

For more information on the supported keys in the default READMODAL() function, refer to the READ command reference in this chapter.

13.22.2.32. Function READVAR()

 READVAR() --> cVarName

13.22.2.33. Function RESTSCREEN()

 RESTSCREEN([<nTop>], [<nLeft>], [<nBottom>], [<nRight>], <cScreen>) --> NIL

13.22.2.34. Function ROW()

 ROW() --> nRow

13.22.2.35. Function SAVESCREEN()

 SAVESCREEN([<nTop>], [<nLeft>], [<nBottom>], [<nRight>]) --> cScreen

13.22.2.36. Function SCROLL()

 SCROLL([<nTop>], [<nLeft>],[<nBottom>], [<nRight>],
 [<nVert>] [<nHoriz>]) --> NIL

13.22.2.38. Function SETCANCEL()

 SETCANCEL([<lToggle>]) --> lCurrentSetting

13.22.2.39. Function SETCOLOR()

 SETCOLOR([<cColorString>]) --> cColorString

13.22.2.39.3. Description

SETCOLOR() is a screen function that saves the current color setting or sets new colors for subsequent screen painting. A color string is made from several color settings, each color corresponding to different regions of the screen. As stated above, each setting is made up of a foreground and background color. Foreground defines the color of characters displayed on the screen. Background defines the color displayed behind the character. Spaces and nondisplay characters display as background.

In xClipper, the settings that define color behavior are:

Standard: The standard setting governs all console, full-screen, and interface commands and functions when displaying to the screen. This includes commands such as @...PROMPT, @...SAY, and ?, as well as functions such as ACHOICE(), DBEDIT(), and MEMOEDIT().

Enhanced: The enhanced setting governs highlighted displays. This includes GETs with INTENSITY ON, and the MENU TO, DBEDIT(), and ACHOICE() selection highlight.

Border: The border is an area around the screen that cannot be written to.

Background: The background is not supported.

Unselected: The unselected setting indicates input focus by displaying the current GET in the enhanced color while other GETs are displayed in the unselected color.

In addition to colors, foreground settings can have high intensity and/or blinking attributes. With a monochrome display, high intensity enhances brightness of painted text. With a color display, high intensity changes the hue of the specified color. For example, "N" displays foreground text as black where "N+" displays the same text as gray. High intensity is denoted by "+". The blinking attribute causes the foreground text to flash on and off at rapid intervals. Blinking is denoted with "*". The attribute character can occur anywhere in the setting string, but is always applied to the foreground color regardless where it occurs. See SETBLINK() for additional information.

The following colors are supported:

 List of Colors
 ------------------------------------------------------------------------
 Color          Letter    Monochrome
 ------------------------------------------------------------------------
 Black          N, Space  Black
 Blue           B         Underline
 Green          G         White
 Cyan           BG        White
 Red            R         White
 Magenta        RB        White
 Brown          GR        White
 White          W         White
 Gray           N+        Black
 Bright Blue    B+        Bright Underline
 Bright Green   G+        Bright White
 Bright Cyan    BG+       Bright White
 Bright Red     R+        Bright White
 Bright Magenta RB+       Bright White
 Yellow         GR+       Bright White
 Bright White   W+        Bright White
 Black          U         Underline
 Inverse Video  I         Inverse Video
 Blank          X         Blank
 ------------------------------------------------------------------------
 

13.22.2.40. Function SETCURSOR()

 SETCURSOR([<nCursorShape>]) --> nCurrentSetting

13.22.2.43. Function SETPRC()

 SETPRC(<nRow>, <nCol>) --> NIL

13.22.2.44. Function TONE()

 TONE(<nFrequency>, <nDuration>) --> NIL

13.22.2.45. Function UPDATED()

 UPDATED() --> lChange