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 |
COL() --> nCol
No arguments
COL() returns an integer numeric value. The range of the return value is zero to MAXCOL().
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.
This example displays a Customer name beginning at column 10. The customer's account status is then displayed to the right of the last character of the customer name using COL(): USE Sales NEW CLS @ 1, 10 SAY "Customer Name: " + TRIM(Customer) @ ROW(), COL() + 1 SAY "Account status: " + Status
COLORSELECT(<nColorIndex>) --> NIL
Always returns 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 ------------------------------------------------------------------------
This example demonstrates use of COLORSELECT() with the Color.ch manifest constants: USE Sales NEW ? SETCOLOR() // displays "W/B,N/B,W/N,W/N,W/N" // in white on blue COLORSELECT(CLR_ENHANCED) // enhanced is active color pair ? "I'm black and blue" // displayed in black on blue COLORSELECT(CLR_STANDARD) // restore standard color
DEVOUT(<exp>, [<cColorString>]) --> NIL
<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. |
DEVOUT() always returns 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.
This example shows the relationship between the DEVOUT() function and the @...SAY command: DEVPOS(10, 10) DEVOUT("Hello there", "BG+/B")) // @ 10, 10 SAY "Hello there" COLOR "BG+/B"
DEVOUTPICT(<exp>, <cPicture>, [<cColorString>]) --> NIL
<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. |
DEVOUTPICT() always returns 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.
This example shows the relationship between the DEVOUTPICT() function and the @...SAY command: DEVPOS(10, 10) DEVOUTPICT("Hello there", "@!", "BG+/B")) // @ 10, 10 SAY "Hello there" PICTURE "@!" COLOR "BG+/B"
DEVPOS(<nRow>, <nCol>) --> NIL
DEVPOS() always returns 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
No arguments
DISPBEGIN() always returns 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.
This example buffers screen output, updates the screen, and then displays the buffered screen output: DISPBEGIN() // Start screen buffering // SETPOS(10, 10) DISPOUT("A display update") SETPOS(11, 10) DISPOUT("Another display update") // DISPEND() // Display buffered screen data
DISPBOX(<nTop>, <nLeft>, <nBottom>, <nRight>, [<cnBoxString>], [<cColorString>]) --> NIL
<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(). |
DISPBOX() always returns 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.
This code example displays a double-line box using a numeric value to specify the box border: #define B_SINGLE 1 #define B_DOUBLE 2 // DISPBOX(1, 1, 10, 10, B_DOUBLE, "BG+/B") This example displays a single-line top and double-line side box by specifying border characters with a manifest constant defined in Box.ch: #include "Box.ch" // DISPBOX(1, 1, 10, 10, B_SINGLE_DOUBLE, "BG+/B") This example displays a box with a 3-D look. It can be used for graphic mode: // Display a box with a 3D look of constant width 16x16x16x16 DISPBOX( nTop, nLeft, nBottom, nRight, LLG_BOX_GRAY_SQUARE ) // Write some transparent text in the 3D frame GWRITEAT( nLeft * GMODE()[LLG_MODE_FONT_COL] ,; nTop * GMODE()[LLG_MODE_FONT_ROW] ,; "This is some Text...",; 4,; LLG_MODE_SET; )
DISPCOUNT() --> nDispCount
No arguments
DISPCOUNT() returns the number of DISPEND() calls required to restore the original display context.
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.
This example saves the setting of DISPCOUNT(), then releases all pending display contexts before writing to the screen: PROCEDURE ForceDisplay(cExp) LOCAL nSavCount nSavCount := DISPCOUNT() // Discard pending display contexts DO WHILE ( DISPCOUNT() > 0) DISPEND() ENDDO DISPOUT(cExp) // "Rewind" the current display context DO WHILE (DISPCCOUNT() < nSavCount ) DISPBEGIN() ENDDO RETURN
DISPEND() --> NIL
No arguments
DISPEND() always returns 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.
This example buffers screen output, updates the screen, and then displays the buffered screen output: DISPBEGIN() // Start screen buffering // SETPOS(10, 10) DISPOUT("A display update") SETPOS(11, 10) DISPOUT("Another display update") // DISPEND() // Display buffered screen data
DISPOUT(<exp>, [<cColorString>]) --> NIL
<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. |
DISPOUT() always returns 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.
This example performs screen output at a specified location in different colors. Note how the cursor position is saved and restored using ROW(), COL(), and SETPOS(): PROCEDURE Showit LOCAL nRow, nCol ? nCol := COL() // save original ?? nRow := ROW() // cursor position INKEY(2) SETPOS(nRow, nCol) DISPOUT("This is a test of DISPOUT()") ? COL() // display current ?? ROW() // cursor position INKEY(2) SETPOS(nRow, nCol) DISPOUT(space(26)) // clear original position SET DEVICE TO PRINTER // ignores SET DEVICE SETPOS(nRow, nCol) // display at DISPOUT(" all through") // original position RETURN
GETACTIVE([<oGet>]) --> objGet
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.
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.
This code uses a WHEN clause to force control to branch to a special reader function. Within this function, GETACTIVE() retrieves the active Get object: @ 10, 10 GET x @ 11, 10 GET y WHEN MyReader() @ 12, 10 GET z READ // Called just before second get (above) // becomes current FUNCTION MyReader LOCAL objGet // Active Get holder objGet := GETACTIVE() // Retrieve current // active Get BarCodeRead( objGet ) RETURN (.F.) // Causes Get to be // skipped in READ
GETAPPLYKEY(<oGet>, <nKey>, <GetList>, <oMenu>, <nMsgRow>, <nMsgLeft>, <nMsgRight>, <cMsgColor>) --> NIL
<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. |
GETAPPLYKEY() always returns 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.
This example will apply keystrokes until Exit: WHILE (oGet:exitState == GE_NOEXIT) GETAPPLYKEY (oGet, INKEY(0), GetList, oMenu, nMsgRow,; nMsgLeft, nMsgRight, nMsgColor) ENDDO
GETDOSETKEY(<bKeyBlock>, <oGet>) --> NIL
GETDOSETKEY() always returns 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().
The following example determines if the last key pressed, nKey, has a SET KEY associated with it. If it does, then GETDOSETKEY is called to execute that block on the current GET. IF ((bKeyBlock := SETKEY (nKey)) == NIL) GETDOSETKEY (bKeyBlock, oGet) ENDIF
GETPOSTVALIDATE(<oGet>) --> lSuccess
GETPOSTVALIDATE() returns a logical value indicating whether the Get object has been postvalidated successfully.
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.).
This example calls GETPOSTVALIDATE to determine whether or not the VALID clause of oGet is satisfied. If not, then the user is not allowed to exit from the Get object. IF (! GETPOSVALIDATE (oGet)) oGet : exitState := GE_NOEXIT ENDIF
GETPREVALIDATE(<oGet>) --> lSuccess
GETPREVALIDATE() returns a logical value indicating whether the Get object has been prevalidated successfully.
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().
This example demonstrates the GETPREVALIDATE() function. IF GETPREVALIDATE (oGet) // process the get ELSE // WHEN clause not satisfied // give a warning to the user ENDIF
GETREADER(<oGet>, <GetList>, <oMenu>, <nMsgRow>, <nMsgLeft>, <nMsgRight>, <cMsgColor>) --> NIL
<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. |
GETREADER() always returns 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.
This example sets the current Get object to the first GET in the Get list. Then, a READ is performed on this GET which has no menu object, but includes a message bar at row 25 from column 0 to column 80. The color of the text on the message bar is white with a red background. oGet := GetList [1] GETREADER (oGet, Getlist, NIL,25,; 0,80,"W+/R")
ISCOLOR() | ISCOLOUR() --> lBoolean
No arguments
ISCOLOR() returns true (.T.) if there is a color graphics card installed; otherwise, it returns false (.F.).
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.).
This example installs color attribute variables at runtime: IF ISCOLOR() cBox = "BG+/B, W/N" cSays = "BG/B, W/N" cGets = "W/N, N/W" ELSE cBox = "W+" cSays = "W/N, N+/W" cGets = "W/N, N/W" ENDIF . . <statements> . SETCOLOR(cSays)
ISPRINTER() --> lReady
No arguments
ISPRINTER() returns true (.T.) if LPT1 is ready; otherwise, it returns false (.F.).
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.
This example tests the parallel port for readiness with up to 25 retries. If the parallel port is ready, the printer operation begins: LOCAL nCount := 0, nTimes := 25, lReady // DO WHILE nCount++ <= nTimes .AND. !(lReady := ; ISPRINTER()) ENDDO // IF lReady REPORT FORM Sales TO PRINTER ELSE ? "Printer not ready..." BREAK ENDIF
MAXCOL() --> nColumn
No arguments
MAXCOL() returns the column number of the rightmost visible column for display purposes.
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().
This example uses MAXROW() and MAXCOL() to determine the area in which to draw a box, and then executes DBEDIT() within the box region: CLS @ 0, 0 TO MAXROW(), MAXCOL() DOUBLE DBEDIT(1, 1, MAXROW() + 1, MAXCOL() - 1)
MAXROW() --> nRow
No arguments
MAXROW() returns the row number of the bottommost visible row for display purposes.
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().
This user-defined function, ScreenSize(), uses MAXROW() and MAXCOL() to return an array containing the current screen size: FUNCTION ScreenSize RETURN { MAXROW(), MAXCOL() }
MENUMODAL(<oTopBar>, <nSelection>, <nMsgRow>, <nMsgLeft>, <nMsgRight>, <cMsgColor>) --> MenuID
<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. |
MENUMODAL() returns the menu ID of the chosen menu item. Menu IDs are assigned using the MenuItem class.
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. ------------------------------------------------------------------------
See the Menu.prg sample file in the \sample directory. This example demonstrates combining TopBarMenu, PopUpMenu, and MenuItem objects to create a menu with a number of available choices. See "Introduction to the Menu System" in the Programming and Utilities Guide for more information about using this function.
NOSNOW(<lToggle>) --> NIL
Returns 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
No arguments
PCOL() returns an integer numeric value representing the last printed column position, plus one. The beginning column position is zero.
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.
In this example, PCOL() creates a simple report that prints a listing of Customer names, addresses, and phone numbers: LOCAL nLine := 99, nPage := 1 USE Customer INDEX CustName NEW SET DEVICE TO PRINTER DO WHILE !EOF() IF nLine > 55 PageTop(nPage) nLine := 1 nPage++ ENDIF @ nLine, 10 SAY CustName @ nLine, PCOL() + 2; SAY RTRIM(City) + ", " + RTRIM(State) + ZipCode; PICTURE REPLICATE("X", 35) @ nLine, PCOL() + 2; SAY Phone; PICTURE "@R (999) 999-9999" nLine++ SKIP ENDDO SET DEVICE TO SCREEN CLOSE
PROW() --> nRow
No arguments
PROW() returns an integer numeric value that represents the number of the current line sent to the printer. The beginning row position is zero.
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.
This example uses PROW() and SETPRC() to create a simple one- across label program that prints with @...SAY instead of ?: USE Customer INDEX CustName NEW SET DEVICE TO PRINTER SETPRC(2, 0) DO WHILE !EOF() @ PROW(), 3 SAY CustName @ PROW() + 1, 3 SAY RTRIM(City) + ",; " + RTRIM(State) + ZipCode @ PROW() + 1, 3 SAY Phone PICTURE "@R ; (999) 999-9999" SETPRC(2, 0) SKIP ENDDO SET DEVICE TO SCREEN CLOSE
READEXIT([<lToggle>]) --> lCurrentState
READEXIT() returns the current setting as a logical value.
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.
This example shows READEXIT() enabling Up arrow and Down arrow exit keys before a READ then resetting them after the READ terminates: cMyvar = SPACE(10) lLastExit = READEXIT(.T.) // Result: Turn on exit keys // @ 10, 10 SAY "Enter: " GET cMyvar READ READEXIT(lLastExit) // Result: Restore previous setting
READFORMAT([<bFormat>]) --> bCurrentFormat
READFORMAT() returns the current format file as a code block. If no format file has been set, READFORMAT() returns NIL.
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.
READINSERT([<lToggle>]) --> lCurrentMode
READINSERT() returns the current insert mode state as a logical value.
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.
This example sets the insert mode prior to entering MEMOEDIT() and resets the mode when MEMOEDIT() terminates: USE Sales NEW // Turn on insert mode lInsMode = READINSERT(.T.) Sales->Notes := MEMOEDIT(Sales->Notes) // // Restore previous insert mode READINSERT(lInsMode)
READKEY() --> nReadkeyCode
No arguments
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 ------------------------------------------------------------------------
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.
READKILL([<lKillRead>]) --> lCurrentSetting
READKILL() returns the current setting as a logical value.
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.
READMODAL(<aGetList>, [<nGet>], [<oMenu>], [<nMsgRow>, <nMsgLeft>, <nMsgRight>, <cMsgColor>]) --> <lUpdated>
<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. |
READMODAL() returns true (.T.) when GetList is updated, false (.F.) when it is not.
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.
READUPDATED([<lChanged>]) --> lCurrentSetting
READUPDATED() returns the current setting as a logical value.
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.
READVAR() --> cVarName
No arguments
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.
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.
This example implements a simple help system for Get objects using a database file to store the help text. When the user presses F1, the help database file is searched using READVAR() as the key value. If there is help text available, it is displayed in a window: #include "Inkey.ch" // SET KEY K_F1 TO HelpLookup cString = SPACE(10) @ 5, 5 SAY "Enter:" GET cString READ RETURN FUNCTION HelpLookup USE Help INDEX Help NEW SEEK READVAR() IF FOUND() DisplayHelp(Help->Topic) ELSE DisplayHelp("No help for " + READVAR()) ENDIF CLOSE Help RETURN NIL FUNCTION DisplayHelp( cTopic ) LOCAL cScreen := SAVESCREEN(5,5,15,70),; cColor := SETCOLOR("BG+/B") // SET CURSOR OFF @ 5, 5 CLEAR TO 15, 70 @ 5, 5 TO 15, 70 DOUBLE @ 5, 30 SAY " Help for " + READVAR() + " " MEMOEDIT(cTopic, 6, 7, 14, 68, .F.) // RESTSCREEN(5, 5, 15, 70, cScreen) SETCOLOR(cColor) SET CURSOR ON // RETURN NIL
RESTSCREEN([<nTop>], [<nLeft>], [<nBottom>], [<nRight>], <cScreen>) --> NIL
<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. |
RESTSCREEN() always returns 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.
This example demonstrates RESTSCREEN() as part of a general purpose pop-up menu function, PopMenu(): ? PopMenu({1, 1, 3, 10, {"ItemOne", "ItemTwo"}, ; "BG+/B"}) FUNCTION PopMenu( aList ) LOCAL cScreen, nChoice, cOldColor := ; SETCOLOR(aList[6]) cScreen := SAVESCREEN(aList[1], aList[2],; aList[3], aList[4]) @ aList[1], aList[2], TO aList[3], aList[4] DOUBLE nChoice := ACHOICE(++aList[1], ++aList[2],; --aList[3], --aList[4], aList[5]) SETCOLOR(cOldColor) RESTSCREEN(--aList[1], --aList[2], ++aList[3],; ++aList[4], cScreen) RETURN nChoice
ROW() --> nRow
No arguments
ROW() returns the cursor row position as an integer numeric value. The range of the return value is zero to MAXROW().
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.
In this example, ROW() simulates the LIST command, displaying text on the same line but in different columns: LOCAL nRow USE Customer INDEX CustName NEW DO WHILE .NOT. EOF() CLS @ 1, 1 SAY PADR("Name", LEN(CustName)) @ ROW(), COL() + 2 SAY PADR("Address", ; LEN(Address)) @ ROW(), COL() + 2 SAY PADR("Phone", LEN(Phone)) nRow = 0 DO WHILE nRow++ <= 15 .AND. (!EOF()) @ ROW() + 1, 1 SAY CustName @ ROW(), COL() + 2 SAY Address @ ROW(), COL() + 2 SAY Phone SKIP ENDDO WAIT ENDDO CLOSE Customer
SAVESCREEN([<nTop>], [<nLeft>], [<nBottom>], [<nRight>]) --> cScreen
SAVESCREEN() returns the specified screen region as a character string.
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.
The following user-defined function creates a pop-up menu using ACHOICE() with SAVESCREEN() and RESTSCREEN(), returning the selection in the array of choices: FUNCTION PopMenu( nTop, nLeft, nBottom, nRight, ; aItems, cColor ) LOCAL cScreen, nChoice, cLastColor := ; SETCOLOR(cColor) // cScreen:= SAVESCREEN(nTop, nLeft, nBottom, nRight) @ nTop, nLeft TO nBottom, nRight DOUBLE // nChoice:= ACHOICE(++nTop, ++nLeft, ; --nBottom, --nRight, aItems) // RESTSCREEN(--nTop, --nLeft, ++nBottom, ++nRight, ; cScreen) SETCOLOR(cLastColor) RETURN nChoice
SCROLL([<nTop>], [<nLeft>],[<nBottom>], [<nRight>], [<nVert>] [<nHoriz>]) --> NIL
<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). |
SCROLL() always returns 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.
This user-defined function displays a message string at the bottom of a screen region after scrolling the region up one line: FUNCTION ScrollUp( nTop, nLeft, nBottom, nRight, ; expDisplay ) // SCROLL(nTop, nLeft, nBottom, nRight, 1) @ nBottom, nLeft SAY expDisplay // RETURN NIL
SETBLINK([<lToggle>]) --> lCurrentSetting
SETBLINK() returns the current setting as a logical value.
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.
This example saves the current SETBLINK() state before passing control to a user-defined function. Upon return, SETBLINK() is restored to its original value: lOldBlink := SETBLINK() MyFunc() SETBLINK(lOldBlink)
SETCANCEL([<lToggle>]) --> lCurrentSetting
SETCANCEL() returns the current setting as a logical value.
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.
This example provides an escape route from a wait state with SETCANCEL() set off: #define K_ALTC 302 // SETCANCEL(.F.) // Disable termination keys SET KEY K_ALTC TO AltC // Redefine Alt-C . . <statements> . RETURN FUNCTION AltC LOCAL cScreen, nChoice, cLastColor := ; SETCOLOR("W/B, N/G") // SAVE SCREEN TO cScreen @ 6, 20 CLEAR TO 9, 58 @ 6, 20 TO 9, 58 DOUBLE @ 7, 26 SAY "Alt-C: Do you want to quit?" @ 8, 35 PROMPT " Yes " @ 8, 41 PROMPT " No " MENU TO nChoice SETCOLOR(cLastColor) RESTORE SCREEN FROM cScreen // IF nChoice = 1 QUIT ENDIF // RETURN NIL
SETCOLOR([<cColorString>]) --> cColorString
<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. |
SETCOLOR() returns the current color settings as a character string.
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 ------------------------------------------------------------------------
This example assigns the current color setting to the variable, cColor: cColor:= SETCOLOR() This example uses SETCOLOR() to save the current color setting and set a new one. cNewColor:= "BR+/N, R+/N" cOldColor:= SETCOLOR(cNewColor) This example uses SET COLOR TO to reset the default colors: SET COLOR TO ? SETCOLOR() // Result: W/N, N/W, N, N, N/W These two examples specify SETCOLOR() with missing settings: // Settings left off the end SETCOLOR("W/N, BG+/B") // // Settings skipped within the list SETCOLOR("W/N, BG+/B,,,W/N") This example uses SETCOLOR() with ISCOLOR() to set the colors, depending on the screen type: FUNCTION DefaultColors IF ISCOLOR() cForm := "W+/N, BG+/B,,,W/N" cDialog := "N/N+, BG+/B,,,N/N+" cAlert := "W+/R, BG+/B,,,W+/R" ELSE cForm := "W+/N, N/W,,,W/N" cDialog := "W+/N, N/W,,,W/N" cAlert := "W+/N, N/W,,,W/N" ENDIF RETURN NIL
SETCURSOR([<nCursorShape>]) --> nCurrentSetting
<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 ------------------------------------------------------------------------ |
SETCURSOR() returns the current cursor shape as a numeric value.
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.
This example uses SETCURSOR() to turn on a full block cursor for the subsequent READ. When the READ terminates, SETCURSOR() turns off the cursor: #include "Setcurs.ch" // USE Customer NEW @ 10, 10 GET Customer->Name @ 11, 10 GET Customer->Phone // SETCURSOR(SC_SPECIAL1) // Change cursor to a block READ SETCURSOR(SC_NONE) // Turn off cursor
SETMODE(<nRows>, <nCols>) --> lSuccess
SETMODE() returns true (.T.) if the mode change was successful; otherwise, it returns false (.F.).
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
This example switches to a 43-line display mode: IF SETMODE(43, 80) ? "43-line mode successfully set" ELSE ? "43-line mode not available" ENDIF This example switches the video mode to regular text mode with 60 rows and 132 columns: // Switch to text mode SET VIDEOMODE( LLG_VIDEO_TXT ) // Set the video mode to the largest number of characters SETMODE( 60,132 )
SETPOS(<nRow>, <nCol>) --> <nRow>
SETPOS() always returns <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.
This example moves the cursor to a new position then displays a string to the screen using a console command, ??: SETPOS(1, 1) ?? "Hello world"
SETPRC(<nRow>, <nCol>) --> NIL
SETPRC() always returns 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.
This user-defined function, PrintCodes(), uses SETPRC() to send control codes to the printer without affecting PROW() and PCOL() values: #include "Set.ch" #define ITALICS_ON CHR(27) + "I" #define ITALICS_OFF CHR(27) + "E" // SET DEVICE TO PRINTER @ 12, 10 SAY "This is an" @ PROW(), PCOL() + 2 SAY PrintCodes(ITALICS_ON) + ; "important" @ PROW(), PCOL() + 2 SAY PrintCodes(ITALICS_OFF) + ; "meeting" SET DEVICE TO SCREEN RETURN FUNCTION PrintCodes( cCtrlCode ) LOCAL nRow, nCol, lPrinter lPrinter := SET(_SET_PRINTER, .T.) // SET PRINTER ON nRow:= PROW() // Save printhead position nCol:= PCOL() // ?? cCtrlCode // Send control code // SETPRC(nRow, nCol) SET(_SET_PRINTER, lPrinter) // Restore printer setting RETURN "" // Return a null string
TONE(<nFrequency>, <nDuration>) --> NIL
<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. |
TONE() always returns 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 ------------------------------------------------------------------------
This example is a beep function that indicates that a batch operation has completed: FUNCTION DoneBeep TONE(300, 1) TONE(100, 1) TONE(300, 1) TONE(100, 1) RETURN NIL This example is a tone sequence that indicates invalid keystrokes or boundary conditions: FUNCTION ErrorBeep TONE(100, 3) RETURN NIL
UPDATED() --> lChange
No arguments
UPDATED() returns true (.T.) if data in a GET is added or changed; otherwise, it returns false (.F.).
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().
This example assigns field values from Customer.dbf to variables and edits them. If the user changes any of the values, the field variables for the current record are updated with the new values: USE Customer NEW CLEAR MEMVAR->Customer = Customer->Customer MEMVAR->Address = Customer->Address @ 1, 1 SAY "Name:" GET MEMVAR->Customer @ 2, 1 SAY "Address:" GET MEMVAR->Address READ // IF UPDATED() Customer->Customer := MEMVAR->Customer Customer->Address := MEMVAR->Address ENDIF