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>]) lCurrentStatREADEXIT([<lToggle>]) bCurrentFormREADFORMAT([<bFormat>]) lCurrentModeREADINSERT([<lToggle>]) nReadkeyCodeREADKEY() lCurrentSettREADKILL([<lKillRead>]) <lUpdated> READMODAL(<aGetList>, [<nGet>], [<oMenu>], [<nMsgRow>, <nMsgLeft>, <nMsgRight>, <cMsgColor>]) lCurrentSettREADUPDATED([<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>]) lCurrentSettSETBLINK([<lToggle>]) lCurrentSettSETCANCEL([<lToggle>]) cColorStringSETCOLOR([<cColorString>]) nCurrentSettSETCURSOR([<nCursorShape>]) bCurrentActiSETKEY(<nInkeyCode>, [<bAction>]) lSuccess SETMODE(<nRows>, <nCols>) <nRow> SETPOS(<nRow>, <nCol>) NIL SETPRC(<nRow>, <nCol>) NIL TONE(<nFrequency>, <nDuration>) lChange UPDATED()
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.
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 ------------------------------------------------------------------------
<nColorIndex> | is a number corresponding to the ordinal positions in the current list of color attributes, as set by SETCOLOR(). |
Returns : | Always returns NIL. |
See also : | SETCOLOR() |
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.
<exp> | is the value to display. |
<cColorString> | is an optional argument that defines the display color of <exp>. If the current DEVICE setting is SCREEN, the output is displayed in the specified color. If not specified, <exp> is displayed as the standard color of the current system color as defined by SETCOLOR(). <cColorString> is a character expression containing the standard color setting. If you want to specify a literal color setting, enclose it in quote marks. |
Returns : | DEVOUT() always returns NIL. |
See also : | COL() DEVPOS() QOUT() ROW() SETPOS() |
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.
<exp> | is the value to display. |
<cPicture> | defines the formatting control for the display of <exp>. The picture specified here is the same as one used with @...SAY or TRANSFORM and can include both templates and functions. |
<cColorString> | is an optional argument that defines the display color of <exp>. If the current DEVICE is SCREEN, output displays in the specified color. If not specified, <exp> displays as the standard color of the current system color as defined by SETCOLOR(). <cColorString> is a character expression containing the standard color setting. If you want to specify a literal color setting, it must be enclosed in quote marks. |
Returns : | DEVOUTPICT() always returns NIL. |
See also : | COL() DEVOUT() DEVPOS() QOUT() ROW() |
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.
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.
Returns : | DISPBEGIN() always returns NIL. |
See also : | DISPEND() DISPCOUNT() |
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.
<nTop> | , <nLeft>, <nBottom>, and <nRight> define the coordinates of the box. DISPBOX() draws a box using row values from zero to MAXROW(), and column values from zero to MAXCOL(). If <nBottom> and <nRight> are larger than MAXROW() and MAXCOL(), the bottom-right corner is drawn off the screen. |
<cnBoxString> | is a numeric or character expression that defines the border characters of the box. If specified as a numeric expression, a value of 1 displays a single-line box and a value of 2 displays a double-line box. All other numeric values display a single-line box. If <cnBoxString> is a character expression, it specifies the characters to be used in drawing the box. This is a string of eight border characters and a fill character. If <cnBoxString> is specified as a single character, that character is used to draw the whole box. If this argument is not specified, a single-line box is drawn. |
<cColorString> | defines the display color of the box that is drawn. If not specified, the box is drawn using the standard color setting of the current system color as defined by SETCOLOR(). |
Returns : | DISPBOX() always returns NIL. |
See also : | SCROLL() |
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.
Returns : | DISPCOUNT() returns the number of DISPEND() calls required to restore the original display context. |
See also : | DISPBEGIN() 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.
Returns : | DISPEND() always returns NIL. |
See also : | DISPBEGIN() DISPCOUNT() |
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.
<exp> | is the value to display. |
<cColorString> | is an optional argument that defines the display color of <exp>. If unspecified, <exp> is displayed as the standard color of the current system color as defined by SETCOLOR(). |
<cColorString> | is a character expression containing the standard color setting. You can specify a literal color setting, if you enclose it in quote marks. |
Returns : | DISPOUT() always returns NIL. |
See also : | COL() OUTSTD() QOUT() ROW() SETCOLOR() SETPOS() |
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.
<oGet> | is a reference to a Get object. |
Returns : | GETACTIVE() returns the Get object referenced by <oGet>. If <oGet> is not specified, then the current active Get object within the current READ is used. If there is no READ active when GETACTIVE() is called, it returns NIL. |
See also : | READMODAL() |
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.
<oGet> | is a reference to a Get object. |
<nKey> | is the INKEY() value to apply to <oGet>. |
<GetList> | is a reference to the current list of Get objects. |
<oMenu> | is a reference to any top bar menu. |
<nMsgRow> | is a numeric value representing the row of the message bar. |
<nMsgLeft> | is a numeric value representing the left column of the message bar. |
<nMsgRight> | is a numeric value representing the right column of the message bar. |
<cMsgColor> | is a character string representing the colors to be used for the message bar text. |
Returns : | GETAPPLYKEY() always returns NIL. |
See also : | GETDOSETKEY() GETPOSTVALIDATE() GETPREVALIDATE() |
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().
<oGet> | is a reference to the current Get object. |
<bKeyBlock> | is the code block to execute. |
Returns : | GETDOSETKEY() always returns NIL. |
See also : | GETAPPLYKEY() GETPOSTVALIDATE() GETPREVALIDATE() |
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.).
<oGet> | is a reference to the current Get object. |
Returns : | GETPOSTVALIDATE() returns a logical value indicating whether the Get object has been postvalidated successfully. |
See also : | GETAPPLYKEY() GETDOSETKEY() 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().
<oGet> | is a reference to the current Get object. |
Returns : | GETPREVALIDATE() returns a logical value indicating whether the Get object has been prevalidated successfully. |
See also : | GETAPPLYKEY() GETDOSETKEY() GETPOSTVALIDATE() |
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.
<oGet> | is a reference to a Get object. |
<GetList> | is an array of all the Get objects in the current Get list. |
<oMenu> | is a reference to a TopBarMenu object. |
<nMsgRow> | is a numeric value representing the row number on the screen where the message bar is located. |
<nMsgLeft> | is a numeric value representing the left border of the row bar. |
<nMsgRight> | is a numeric value representing the right border of the row bar. |
<cMsgColor> | is a character string representing the color string to be used for the message bar. |
Returns : | GETREADER() always returns NIL. |
See also : | GETAPPLYKEY() GETDOSETKEY() GETPOSTVALIDATE() |
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.).
Returns : | ISCOLOR() returns true (.T.) if there is a color graphics card installed; otherwise, it returns false (.F.). |
See also : | SETCOLOR() |
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.
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().
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().
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. ------------------------------------------------------------------------
<oTopBar> | is a TopBarMenu object created from the TopBarMenu class. |
<nSelection> | is the TopBarMenu item selected by default. |
<nMsgRow> | is the row number where menu item messages will appear. |
<nMsgLeft> | specifies the left border for menu item messages. |
<nMsgRight> | specifies the right border for menu item messages. |
<cMsgColor> | defines the color string for the menu item messages. It consists of a single foreground/background pair. |
Returns : | MENUMODAL() returns the menu ID of the chosen menu item. Menu IDs are assigned using the MenuItem class. |
See also : |
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.
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.
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.
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.
<lToggle> | toggles the use of Up arrow and Down arrow as READ exit keys. Specifying true (.T.) enables them as exit keys, and false (.F.) disables them. |
Returns : | READEXIT() returns the current setting as a logical value. |
See also : | READINSERT() |
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.
<bFormat> | is the name of the code block, if any, to use for implementing a format file. If no argument is specified, the function simply returns the current code block without setting a new one. |
Returns : | READFORMAT() returns the current format file as a code block. If no format file has been set, READFORMAT() returns NIL. |
See also : | READKILL() READUPDATED() |
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.
<lToggle> | toggles the insert mode on or off. True (.T.) turns insert on, while false (.F.) turns insert off. The default is false (.F.) or the last user-selected mode in READ or MEMOEDIT(). |
Returns : | READINSERT() returns the current insert mode state as a logical value. |
See also : | READEXIT() MEMOEDIT() |
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.
Returns : | READKEY() returns a code representing the key pressed to exit a READ. In xClipper, the following keys are the standard READ exit keys and their READKEY() return codes: READKEY() Return Codes ------------------------------------------------------------------------ Exit Key Return Code ------------------------------------------------------------------------ Up arrow 5 Down arrow 2 PgUp 6 PgDn 7 Ctrl+PgUp 31 Ctrl+PgDn 30 Esc 12 Ctrl+End, Ctrl+W 14 Type past end 15 Return 15 ------------------------------------------------------------------------ |
See also : | NEXTKEY() READEXIT() LASTKEY() UPDATED() |
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.
<lKillRead> | sets the READKILL() flag. A value of true (.T.) indicates that the current read should be terminated, and a value of false (.F.) indicates that it should not. |
Returns : | READKILL() returns the current setting as a logical value. |
See also : | READFORMAT() READUPDATED() READMODAL() READVAR() |
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.
<aGetList> | is an array containing a list of Get objects to edit. |
<nGet> | is an optional numeric value that indicates which Get object within <aGetList> should initially receive input focus. |
<oMenu> | is an optional Topbarmenu object that, when supplied, permits menu selection during data entry. |
<nMsgRow> | , <nMsgLeft>, and <nMsgRight> specify the row, left, and right margins where the Get object messages appear on the screen. |
<cMsgColor> | defines the color setting of the message area. It consists of a single foreground/background color pair. |
Returns : | READMODAL() returns true (.T.) when GetList is updated, false (.F.) when it is not. |
See also : | UPDATED() |
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.
<lChanged> | sets the READUPDATED() flag. A value of true (.T.) indicates that data has changed, and a value of false (.F.) indicates that no change has occurred. |
Returns : | READUPDATED() returns the current setting as a logical value. |
See also : | READFORMAT() READKILL() UPDATED() |
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.
Returns : | READVAR() returns the name of the variable associated with the current Get object or the variable being assigned by the current MENU TO command as an uppercase character string. |
See also : | READMODAL() READKILL() |
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.
<nTop> | , <nLeft>, <nBottom>, and <nRight> define the coordinates of the screen information contained in <cScreen>. If |
<cScreen> | was saved without coordinates to preserve the entire screen, no screen coordinates are necessary with RESTSCREEN(). |
<cScreen> | is a character string containing the saved screen region. |
Returns : | RESTSCREEN() always returns NIL. |
See also : | SAVESCREEN() |
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.
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.
<nTop> | , <nLeft>, <nBottom>, and <nRight> define the coordinates of the screen region to be saved. If either <nBottom> or |
<nRight> | is greater than MAXROW() or MAXCOL(), the screen is clipped. If you specify no coordinates, the entire screen (i.e., from 0,0 to MAXROW(), MAXCOL()) is saved. |
Returns : | SAVESCREEN() returns the specified screen region as a character string. |
See also : | RESTSCREEN() |
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.
<nTop> | , <nLeft>, <nBottom>, and <nRight> define the scroll region coordinates. Row and column values can range from 0, 0 to MAXROW(), MAXCOL(). If you do not specify coordinate arguments, the dimensions of the visible display are used. |
<nVert> | defines the number of rows to scroll vertically. A positive value scrolls up the specified number of rows. A negative value scrolls down the specified number of rows. A value of zero disables vertical scrolling. If <nVert> is not specified, zero is assumed. |
<nHoriz> | defines the number of rows to scroll horizontally. A positive value scrolls left the specified number of columns. A negative value scrolls right the specified number of columns. A value of zero disables horizontal scrolling. If <nHoriz> is not specified, zero is assumed. If you supply neither the <nVert> nor <nHoriz> parameters to SCROLL(), the area specified by the first four parameters will be blanked. Warning! Horizontal scrolling is not supported on all of the alternate terminal drivers (i.e., ANSITERM, NOVTERM, PCBIOS). |
Returns : | SCROLL() always returns NIL. |
See also : | DISPBOX() |
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.
<lToggle> | changes the meaning of the asterisk (*) character when it is encountered in a SETCOLOR() string. Specifying true (.T.) sets character blinking on, and false (.F.) sets background intensity. The default is true (.T.). |
Returns : | SETBLINK() returns the current setting as a logical value. |
See also : | SETCOLOR() |
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.
<lToggle> | changes the availability of Alt+C and Ctrl+Break as termination keys. Specifying true (.T.) allows either of these keys to terminate an application and false (.F.) disables both keys. The default is true (.T.). |
Returns : | SETCANCEL() returns the current setting as a logical value. |
See also : | SETKEY() |
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 ------------------------------------------------------------------------
<cColorString> | is a character string containing a list of color attribute settings for subsequent screen painting. The following is a list of settings and related scopes: Color Settings ------------------------------------------------------------------------ Setting Scope ------------------------------------------------------------------------ Standard All screen output commands and functions Enhanced GETs and selection highlights Border Border around screen, not supported on EGA and VGA Background Not supported Unselected Unselected GETs ------------------------------------------------------------------------Each setting is a foreground and background color pair separated by the slash (/) character and followed by a comma. All settings are optional. If a setting is skipped, its previous value is retained with only new values set. Settings may be skipped within the list or left off the end as illustrated in the examples below. |
Returns : | SETCOLOR() returns the current color settings as a character string. |
See also : | ISCOLOR() |
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.
<nCursorShape> | is a number indicating the shape of the cursor. For simpler coding, the Setcurs.ch header file provides descriptive names for the various cursor shapes as shown in the table below: Cursor Shapes ------------------------------------------------------------------------ Shape Value Setcurs.ch ------------------------------------------------------------------------ None 0 SC_NONE Underline 1 SC_NORMAL Lower half block 2 SC_INSERT Full block 3 SC_SPECIAL1 Upper half block 4 SC_SPECIAL2 ------------------------------------------------------------------------ |
Returns : | SETCURSOR() returns the current cursor shape as a numeric value. |
See also : | SETPOS() |
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
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.
<nRow> | and <nCol> define the new screen position of the cursor. These values may range from 0, 0 to MAXROW(), MAXCOL(). |
Returns : | SETPOS() always returns <nRow> |
See also : | ROW() SETCURSOR() COL() |
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.
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 ------------------------------------------------------------------------
<nFrequency> | is a positive numeric value indicating the frequency of the tone to be sounded. |
<nDuration> | is a positive numeric value indicating the duration of the tone measured in increments of 1/18 of a second. For example, an |
<nDuration> | value of 18 represents one second. For both arguments, non-integer values are truncated--not rounded--to their integer portion. |
Returns : | TONE() always returns NIL. |
See also : | CHR() |
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().
Returns : | UPDATED() returns true (.T.) if data in a GET is added or changed; otherwise, it returns false (.F.). |
See also : | READMODAL() |