TERMINAL/IO

Name

TERMINAL/IO -- 

Function

nPosition           ACHOICE(<nTop>, <nLeft>, <nBottom>, <nRight>, <acMenuItems>, [<alSelectableItems> | <lSelectableItems>], [<cUserFunction>], [<nInitialItem>], [<nWindowRow>])
nChoice             ALERT( <cMessage>, [<aOptions>] )
nCol                COL()
NIL                 COLORSELECT(<nColorIndex>)
NIL                 DEVOUT(<exp>, [<cColorString>])
NIL                 DEVOUTPICT(<exp>, <cPicture>, [<cColorString>])
NIL                 DEVPOS(<nRow>, <nCol>)
NIL                 DISPBEGIN()
NIL                 DISPBOX(<nTop>, <nLeft>, <nBottom>, <nRight>, [<cnBoxString>], [<cColorString>])
nDispCount          DISPCOUNT()
NIL                 DISPEND()
NIL                 DISPOUT(<exp>, [<cColorString>])
objGet              GETACTIVE([<oGet>])
NIL                 GETAPPLYKEY(<oGet>, <nKey>, <GetList>, <oMenu>, <nMsgRow>, <nMsgLeft>, <nMsgRight>, <cMsgColor>)
NIL                 GETDOSETKEY(<bKeyBlock>, <oGet>)
lSuccess            GETPOSTVALIDATE(<oGet>)
lSuccess            GETPREVALIDATE(<oGet>)
NIL                 GETREADER(<oGet>, <GetList>, <oMenu>, <nMsgRow>, <nMsgLeft>, <nMsgRight>, <cMsgColor>)
lBoolean            ISCOLOR() | ISCOLOUR()
lReady              ISPRINTER()
nColumn             MAXCOL()
nRow                MAXROW()
MenuID              MENUMODAL(<oTopBar>, <nSelection>, <nMsgRow>, <nMsgLeft>, <nMsgRight>, <cMsgColor>)
NIL                 NOSNOW(<lToggle>)
NIL                 OUTERR(<exp list>)
NIL                 OUTSTD(<exp list>)
nColumn             PCOL()
nRow                PROW()
NIL                 QOUT([<exp list>]) --> NIL QQOUT([<exp list>])
lCurrentState       READEXIT([<lToggle>])
bCurrentFormat      READFORMAT([<bFormat>])
lCurrentMode        READINSERT([<lToggle>])
nReadkeyCode        READKEY()
lCurrentSetting     READKILL([<lKillRead>])
<lUpdated>          READMODAL(<aGetList>, [<nGet>], [<oMenu>], [<nMsgRow>, <nMsgLeft>, <nMsgRight>, <cMsgColor>])
lCurrentSetting     READUPDATED([<lChanged>])
cVarName            READVAR()
NIL                 RESTSCREEN([<nTop>], [<nLeft>], [<nBottom>], [<nRight>], <cScreen>)
nRow                ROW()
cScreen             SAVESCREEN([<nTop>], [<nLeft>], [<nBottom>], [<nRight>])
NIL                 SCROLL([<nTop>], [<nLeft>],[<nBottom>], [<nRight>], [<nVert>] [<nHoriz>])
lCurrentSetting     SETBLINK([<lToggle>])
lCurrentSetting     SETCANCEL([<lToggle>])
cColorString        SETCOLOR([<cColorString>])
nCurrentSetting     SETCURSOR([<nCursorShape>])
bCurrentAction      SETKEY(<nInkeyCode>, [<bAction>])
lSuccess            SETMODE(<nRows>, <nCols>)
<nRow>              SETPOS(<nRow>, <nCol>)
NIL                 SETPRC(<nRow>, <nCol>)
NIL                 TONE(<nFrequency>, <nDuration>)
lChange             UPDATED()

Description

Function COL()

 COL() --> nCol

COL() is a screen function that returns the current column position of the cursor. The value of COL() changes whenever the cursor position changes on the screen. Both console and full-screen commands can change the cursor position. In addition, COL() is automatically set to zero whenever a CLEAR, CLEAR SCREEN, or CLS command is executed.

Use COL() to position the cursor to a column relative to the current column. It is generally used in combination with ROW() and all variations of the @ command. In particular, use COL() and ROW() to create screen position-independent procedures or functions that pass the upper-left row and column as parameters.

If DEVICE is SET TO PRINTER, all the output of @...SAY commands is directed to the printer and PROW() and PCOL() are updated instead of ROW() and COL(). Use these functions when you need to determine the position of the printhead.

Function COLORSELECT()

 COLORSELECT(<nColorIndex>) --> NIL

COLORSELECT() activates the specified color pair from the current list of color attributes (established by SETCOLOR()). Manifest constants for <nColorIndex> are defined in Color.ch.

 Color.ch constants
 ------------------------------------------------------------------------
 Constant          Value
 ------------------------------------------------------------------------
 CLR_STANDARD      0
 CLR_ENHANCED      1
 CLR_BORDER        2
 CLR_BACKGROUND    3
 CLR_UNSELECTED    4
 ------------------------------------------------------------------------
 

COLORSELECT() does not alter the current SET Color setting.

This table describes the scope of the xClipper color settings affected by SETCOLOR():

 Color settings
 ------------------------------------------------------------------------
 Setting        Scope
 ------------------------------------------------------------------------
 Standard       All screen output commands and functions
 Enhanced       GETs and selection highlights
 Border         Screen border (not supported on EGA and VGA monitors)
 Background     Not supported
 Unselected     Unselected GETs
 ------------------------------------------------------------------------
 

Function DEVOUT()

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

DEVOUT() is a full-screen display function that writes the value of a single expression to the current device at the current cursor or printhead position. Use DEVOUT() with DEVPOS() in Std.ch to implement the @...SAY command.

Function DEVOUTPICT()

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

DEVOUTPICT() is a full-screen display function that writes the value of a single expression to the current device at the current cursor or printhead position. DEVOUTPICT() is used in combination with DEVPOS() in Std.ch to implement the @...SAY command used with a PICTURE clause.

Function DEVPOS()

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

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.

Function DISPBEGIN()

 DISPBEGIN() --> NIL

DISPBEGIN() is a screen function that informs the xClipper display output system that the application is about to perform a series of display operations.

Use DISPBEGIN() with DISPEND() to allow the display output system to buffer display updates. Display output which occurs after DISPBEGIN() but before DISPEND() is allowed to accumulate in internal buffers. When DISPEND() executes, any pending updates appear on the physical display. This is useful in applications where complex screen displays are slow and the appearance of performance is desired.

DISPBEGIN() and DISPEND() calls are optional. They are not required for normal output.

Function DISPBOX()

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

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.

Function DISPCOUNT()

 DISPCOUNT() --> nDispCount

You can use DISPCOUNT() to determine the current display context. xClipper uses display contexts to buffer and to supervise screen output operations.

Each call to DISPBEGIN() defines a new display context. Output to the display context is suppressed until a matching DISPEND() statement executes.

Since you may nest DISPBEGIN() calls, use DISPCOUNT() to determine whether there are pending screen refresh requests.

Function DISPEND()

 DISPEND() --> NIL

DISPEND() is a screen function that informs the xClipper display output system that the application has finished performing a series of display operations.

DISPEND() is used with DISPBEGIN() so the display output system can buffer display updates. This can be important for applications in which complex screen displays are slow and the appearance of performance is desired.

Function DISPOUT()

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

DISPOUT() is a simple output function that writes the value of a single expression to the display at the current cursor position. This function ignores the SET DEVICE setting; output always goes to the screen. You can only use this function within a procedure or function.

Function GETACTIVE()

 GETACTIVE([<oGet>]) --> objGet

GETACTIVE() is an environment function that provides access to the active Get object during a READ. The current active Get object is the one with input focus at the time GETACTIVE() is called.

Function GETAPPLYKEY()

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

GETAPPLYKEY() is a Get system function that applies an INKEY() value to a Get object. Keys are applied in the default way. That is, cursor movement keys change the cursor position within the GET, data keys are entered into the GET, etc.

If the key supplied to GETAPPLYKEY() is a SET KEY, GETAPPLYKEY() will execute the set key and return; the key is not applied to the Get object.

Function GETDOSETKEY()

 GETDOSETKEY(<bKeyBlock>, <oGet>) --> NIL

GETDOSETKEY() is a function that executes a SET KEY code block, preserving the context of the passed Get object.

Note that the procedure name and line number passed to the SET KEY block are based on the most recent call to READMODAL().

Function GETPOSTVALIDATE()

 GETPOSTVALIDATE(<oGet>) --> lSuccess

GETPOSTVALIDATE() is a Get system function that validates a Get object after editing, including evaluating Get:postBlock (the VALID clause) if present.

The return value indicates whether the GET has been postvalidated successfully. If a CLEAR GETS is issued during postvalidation, Get:exitState is set to GE_ESCAPE and GETPOSTVALIDATE() returns true (.T.).

Function GETPREVALIDATE()

 GETPREVALIDATE(<oGet>) --> lSuccess

GETPREVALIDATE() is a function that validates the Get object for editing, including evaluating Get:preBlock (the WHEN clause) if it is present. The logical return value indicates whether the GET has been prevalidated successfully.

Get:exitState is also set to reflect the outcome of the prevalidation:

 Get:exitState Values
 ------------------------------------------------------------------------
 Getexit.ch   Meaning
 ------------------------------------------------------------------------
 GE_NOEXIT    Indicates prevalidation success, okay to edit
 GE_WHEN      Indicates prevalidation failure
 GE_ESCAPE    Indicates that a CLEAR GETS was issued
 ------------------------------------------------------------------------
 

Note that in the default system, a Get:exitState of GE_ESCAPE cancels the current GET and terminates READMODAL().

Function GETREADER()

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

GETREADER() is a GET function that implements the standard READ behavior for GETs. By default, READMODAL() uses the GETREADER() function to read Get objects. GETREADER() in turn uses other functions in Getsys.prg to do the work of reading the Get object.

Function ISCOLOR()

 ISCOLOR() | ISCOLOUR() --> lBoolean

ISCOLOR() is a screen function that allows you to make decisions about the type of screen attributes to assign (color or monochrome). Note that some monochrome adapters with graphics capability return true (.T.).

Function ISPRINTER()

 ISPRINTER() --> lReady

ISPRINTER() is a printer function that determines whether the parallel port (LPT1) is online and ready to print. ISPRINTER() is hardware-dependent and, therefore, only works on IBM BIOS compatible systems.

You can check ISPRINTER() to make sure the printer is ready before you begin a print operation; however, if an error occurs during the print operation, a runtime error is generated.

Function MAXCOL()

 MAXCOL() --> nColumn

MAXCOL() is a screen function that determines the maximum visible column of the screen. Row and column numbers start at zero in xClipper.

If you use a C or other extended function to set the video mode, use the SETMODE() function so your xClipper application returns the correct value for MAXCOL().

Function MAXROW()

 MAXROW() --> nRow

MAXROW() is a screen function that determines the maximum visible row of the screen. Row and column numbers start at zero in xClipper.

If you use a C or other extended function to set the video mode, use the SETMODE() function so your xClipper application returns the correct value for MAXCOL().

Function MENUMODAL()

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

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.
 ------------------------------------------------------------------------
 

Function NOSNOW()

 NOSNOW(<lToggle>) --> NIL

NOSNOW() is used to suppress snow on CGA monitors. Typically, use NOSNOW() in the configuration section of your application to give the user the option to suppress snow.

Function PCOL()

 PCOL() --> nColumn

PCOL() is a printer function that reports the column position of the printhead after the last print operation. PCOL() is updated only if either SET DEVICE TO PRINTER or SET PRINTER ON is in effect. PCOL() is the same as COL() except that it relates to the printer rather than the screen. PCOL() is updated in the following ways:

Application startup sets PCOL() to zero

EJECT resets PCOL() to zero

A print operation sets PCOL() to the last column print position plus one

SETPRC() sets PCOL() to the specified column position

PCOL(), used with PROW(), prints a value relative to the last value printed on the same line. This makes it easier to align columns when printing a columnar report. A value is printed in the next column by specifying its position as PCOL() + <column offset>. Note that PCOL() is effective for alignment only if the column values are fixed-width. To guarantee fixed-width column values, format the output using TRANSFORM(), the PICTURE clause of @...SAY, or any of the PAD() functions.

Function PROW()

 PROW() --> nRow

PROW() is a printer function that reports the row position of the printhead after the last print operation. PROW() is updated only if either SET DEVICE TO PRINTER or SET PRINTER ON is in effect. PROW() is like ROW() except that it relates to the printer rather than the screen. PROW() is updated in the following ways:

Application startup sets PROW() to zero

EJECT resets PROW() to zero

A print operation sets PROW() to the last row print position

SETPRC() sets PROW() to the specified row position

PROW() used with PCOL() prints a value to a new row relative to the last row printed. If the printhead is positioned to a new row with a control code, a line feed (CHR(10)), or form feed (CHR(12)), PROW() is not updated and, therefore, will not return the expected value. To prevent this discrepancy, reset PROW() to the correct value with SETPRC() after sending any of these characters to the printer.

Function READEXIT()

 READEXIT([<lToggle>]) --> lCurrentState

READEXIT() is an environment function that reports the current state of Up arrow and Down arrow as keys the user can press to exit a READ from the first or last Get object in a GetList. If the optional <lToggle> argument is specified, Up arrow and Down arrow are either enabled or disabled as READ exit keys. At program startup, Up arrow and Down arrow are not enabled as READ exit keys. Normally, READ exit keys include only Pgup, Pgdn, Esc, or Return from the last GET.

Function READFORMAT()

 READFORMAT([<bFormat>]) --> bCurrentFormat

READFORMAT() is a Get system function that accesses the current format file in its internal code block representation. It lets you manipulate the format file code block from outside of the Get system's source code.

To set a format file, use SET FORMAT (see the SET FORMAT entry ) or READFORMAT().

READFORMAT() is intended primarily for creating new READ layers. The code block that READFORMAT() returns, when evaluated, executes the code that is in the format file from which it was created.

Function READINSERT()

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

READINSERT() is an environment function that reports the current state of the insert mode for READ and MEMOEDIT() and, optionally, sets the insert mode on or off depending on the value of <lToggle>. When READINSERT() returns false (.F.) and the user enters characters into a Get object's buffer during a READ or a MEMOEDIT(), characters are overwritten. When READINSERT() returns true (.T.), entered characters are inserted instead. The insert mode is a global setting belonging to the system and not to any specific object.

You can execute READINSERT() prior to or during a READ or MEMOEDIT(). If used with READ, READINSERT() can be invoked within a WHEN or VALID clause of @...GET or within a SET KEY procedure. If used with MEMOEDIT(), it can be invoked with the user function as well as a SET KEY procedure.

Function READKEY()

 READKEY() --> nReadkeyCode

READKEY() is a keyboard function that emulates the READKEY() function in dBASE III PLUS. Its purpose is to determine what key the user pressed to terminate a READ. If UPDATED() is true (.T.), READKEY() returns the code plus 256. Up arrow and Down arrow exit a READ only if READEXIT() returns true (.T.). The default value is false (.F.). To provide complete compatibility for these keys, execute a READEXIT (.T.) at the beginning of your main procedure.

READKEY() is supplied as a compatibility function and, therefore, its use is strongly discouraged. It is superseded entirely by LASTKEY() which determines the last keystroke fetched from the keyboard buffer. If the keystroke was a READ exit key, LASTKEY() will return the INKEY() code for that key. To determine whether any Get object's buffer was modified during a READ, it is superseded by the UPDATED() function.

Function READKILL()

 READKILL([<lKillRead>]) --> lCurrentSetting

READKILL() is a Get system function that lets you control whether or not to terminate the current READ.

Unless directly manipulated, READKILL() returns true (.T.) after you issue a CLEAR GETS (see the CLEAR GETS entry ) for the current READ; otherwise, it returns false (.F.).

By accessing the function directly, however, you can control the READKILL() flag with its function argument and use it to create new READ layers.

Function READMODAL()

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

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.

Function READUPDATED()

 READUPDATED([<lChanged>]) --> lCurrentSetting

READUPDATED() is a Get system function intended primarily for creating new READ Layers. It is identical in functionality to UPDATED() (see the UPDATED() entry ), except that it allows the UPDATED() flag to be set.

READUPDATED() enables you to manipulate the UPDATED() flag from outside of the Get system's source code.

Function READVAR()

 READVAR() --> cVarName

READVAR() is an environment function that primarily implements context- sensitive help for Get objects and lightbar menus. READVAR() only works during a READ or MENU TO command. If used during any other wait states, such as ACCEPT, INPUT, WAIT, ACHOICE(), DBEDIT(), or MEMOEDIT(), it returns a null string (""). Access it within a SET KEY procedure, or within a user-defined function invoked from a WHEN or VALID clause of a Get object.

Function RESTSCREEN()

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

RESTSCREEN() is a screen function that redisplays a screen region saved with SAVESCREEN(). The target screen location may be the same as or different from the original location when the screen region was saved. If you specify a new screen location, the new screen region must be the same size or you will get ambiguous results. To use RESTSCREEN() to restore screen regions saved with SAVE SCREEN, specify the region coordinates as 0, 0, MAXROW(), MAXCOL().

Warning! SAVE SCREEN, RESTORE SCREEN, SAVESCREEN(), and RESTSCREEN() are supported when using the default (IBM PC memory mapped) screen driver. Other screen drivers may not support saving and restoring screens.

Function ROW()

 ROW() --> nRow

ROW() is a screen function that returns the current row or line position of the screen cursor. The value of ROW() is updated by both console and full-screen commands and functions. @...SAY only updates ROW() when the current DEVICE is the SCREEN.

ROW() is used with COL() and all variations of the @ command to position the cursor to a new line relative to the current line. In particular, you can use ROW() and COL() to create screen position-independent procedures or functions where you pass the upper-left row and column as parameters.

ROW() is related to PROW() and PCOL(), which track the current printhead position instead of the screen cursor position.

Function SAVESCREEN()

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

SAVESCREEN() is a screen function that saves a screen region to a variable of any storage class including a field variable. Later, you can redisplay the saved screen image to the same or a new location using RESTSCREEN(). Screen regions are usually saved and restored when using a pop-up menu routine or dragging a screen object.

Warning! SAVE SCREEN, RESTORE SCREEN, SAVESCREEN(), and RESTSCREEN() are supported when using the default (IBM PC memory mapped) screen driver. Other screen drivers may not support saving and restoring screens.

Function SCROLL()

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

SCROLL() is a screen function that scrolls a screen region up or down a specified number of rows. When a screen scrolls up, the first line of the region is erased, all other lines are moved up, and a blank line is displayed in the current standard color on the bottom line of the specified region. If the region scrolls down, the operation is reversed. If the screen region is scrolled more than one line, this process is repeated.

SCROLL() is used primarily to display status information into a defined screen region. Each time a new message is displayed, the screen region scrolls up one line and a new line displays at the bottom.

Function SETBLINK()

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

SETBLINK() is an environment function that toggles the blinking/background intensity attribute and reports the current state of SETBLINK(). When SETBLINK() is on, characters written to the screen can be made to blink by including an asterisk (*) in a color string passed to SETCOLOR(). When SETBLINK() is off, the asterisk (*) causes the background color to be intensified instead. Thus, blinking and background intensity attributes are not available at the same time.

Note: This function is meaningful only on the IBM PC or compatible computers with CGA, EGA, or VGA display hardware.

Function SETCANCEL()

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

SETCANCEL() is a keyboard function that toggles the state of the termination keys, Alt+C and Ctrl+Break, and reports the current state of SETCANCEL(). Use SETCANCEL() when you want to suppress a user's ability to terminate a program without using the specified method.

Note that if Alt+C or Ctrl+Break is redefined with SET KEY, the SET KEY definition takes precedence even if SETCANCEL() returns true (.T.).

Warning! When SETCANCEL() has been set to false (.F.), the user cannot terminate a runaway program unless you provide an alternative escape mechanism.

Function SETCOLOR()

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

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
 ------------------------------------------------------------------------
 

Function SETCURSOR()

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

SETCURSOR() is an environment function that controls the shape of the screen cursor. The actual shape is dependent on the current screen driver. The specified shapes appear on IBM PC and compatible computers. On other computers, the appearance may differ for each value specified.

SETCURSOR(0) is the same as SET CURSOR OFF, and any positive integer value of <nCursorShape> less than 5 is the same as SET CURSOR ON. The cursor will display as the selected shape.

Function SETMODE()

 SETMODE(<nRows>, <nCols>) --> lSuccess

SETMODE() is an environment function that attempts to change the mode of the display hardware to match the number of rows and columns specified. The change in screen size is reflected in the values returned by MAXROW() and MAXCOL().

Note: In LLG_VIDEO_TXT mode, and when a VESA driver is present, it is possible to use the following values : 25,80 | 43,80 | 50,80 | 60,80 | 25,132 | 43,132 | 50,132 | 60,132

Function SETPOS()

 SETPOS(<nRow>, <nCol>) --> <nRow>

SETPOS() is an environment function that moves the cursor to a new position on the screen. After the cursor is positioned, ROW() and COL() are updated accordingly. To control the shape and visibility of the cursor, use the SETCURSOR() function.

Function SETPRC()

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

SETPRC() is a printer function that sends control codes to the printer without changing the tracking of the printhead position. When xClipper prints, it updates the PCOL() value with the number of characters sent to the printer. There is no discrimination between printable or nonprintable characters. If, for example, a string of ten characters sent to the printer contains two characters interpreted by the printer as a control code, the xClipper PCOL() value is incremented by ten, while the true printhead position is moved only by eight. This can lead to alignment problems. Using SETPRC(), you can compensate for control codes by resetting PCOL() as shown in the example below.

SETPRC() also suppresses page ejects when printing with @...SAY. This is important when the next row position is smaller than the current row and an EJECT has not been issued. In this situation, xClipper issues an automatic page eject if the next row print position is less than the current PROW() value. Using SETPRC(), you can set PROW() to a number less than the current row, thus suppressing the automatic EJECT.

Function TONE()

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

TONE() is a sound function that indicates various program states to the user. These can be error states, boundary conditions, or the end of a time-consuming process. For example, an error state would sound an error tone before alerting the user with a message or interactive dialog box. A boundary condition might indicate that the user is attempting to move the cursor past the top or bottom of a column in a TBrowse object. A batch process also might indicate its completion with a sound to alert the user, in case the user has turned away from the screen.

TONE() works by sounding the speaker at the specified frequency for the specified duration. The duration is measured in increments of 1/18 of a second. The frequency is measured in hertz (cycles per second). Frequencies of less than 20 are inaudible. The table below shows the frequencies of standard musical notes.

Note: TONE() works only on IBM PC and 100 percent compatible computers.

Table of Musical Notes
 ------------------------------------------------------------------------
 Pitch   Frequency    Pitch     Frequency
 ------------------------------------------------------------------------
 C       130.80       mid C     261.70
 C#      138.60       C#        277.20
 D       146.80       D         293.70
 D#      155.60       D#        311.10
 E       164.80       E         329.60
 F       174.60       F         349.20
 F#      185.00       F#        370.00
 G       196.00       G         392.00
 G#      207.70       G#        415.30
 A       220.00       A         440.00
 A#      233.10       A#        466.20
 B       246.90       B         493.90
 C         523.30
 ------------------------------------------------------------------------
 

Function UPDATED()

 UPDATED() --> lChange

UPDATED() determines whether characters were successfully entered into a GET from the keyboard during the most current READ. Each time READ executes, UPDATED() is set to false (.F.). Then, any change to a GET entered from the keyboard sets UPDATED() to true (.T.) after the user successfully exits the GET. If the user presses Esc before exiting the first GET edited, UPDATED() remains false (.F.). Once UPDATED() is set to true (.T.), it retains this value until the next READ is executed.

Within a SET KEY or VALID procedure, you can change the current GET variable using the KEYBOARD command or by assigning a new value with one of the many assignment operators. Changing the variable with KEYBOARD is the same as if the user had entered the change directly from the keyboard, and UPDATED() is set accordingly. However, since UPDATED() reflects only those changes made from the keyboard, an assignment to the GET variable does not affect UPDATED().