Displays a box on the screen.


      DispBox( <nTop>, <nLeft>, <nBottom>, <nRight>, ;
             [<cnBoxString>] , [<cColor>] ) --> NIL


<nTop> and <nLeft> : screen coordinates for the upper left corner of the DispBox()output

<nBottom> and <nRight> : screen coordinates for the lower right corner of the DispBox()output

<cnBoxString> : The appearance of the box to display can either be specified as numeric 1 (single line box), numeric 2 (double line box), or as a character string holding up to nine characters. The first eight characters define the border of the box while the ninth character is used to fill the box. #define constants to be used for <cnBoxString> are available in the BOX.CH #include file.

Pre-defined box strings for DispBox()

         Constant        Description
         --------------- ----------------------------------------
         B_SINGLE        Single-line box
         B_DOUBLE        Double-line box
         B_SINGLE_DOUBLE Single-line top, double-line sides
         B_DOUBLE_SINGLE Double-line top, single-line sides

If no <cnBoxString> is specified, a single-line box is drawn. <cColor> : SetColor() compliant color string; default is the standard color of SetColor().


DispBox() returns always NIL.


The function DispBox() displays a box on the screen as specified with <cnBoxString>, using the standard color of SetColor() or <cColor>, if specified.

If a character string is used for <cnBoxString>, the first eight characters define the border of the box in clockwise direction, beginning with the upper left corner. An optional ninth character fills the area inside the box. Alternatively, a single character can be passed which is used to draw the entire box border. When the box is completely drawn, the cursor is positioned at the coordinates <nTop>+1 and <nLeft>+1, so that a subsequent DispOut() call starts displaying in the upper left corner of the box area.


      // The example demonstrates how characters are used to draw a box.
      // Alphabetic characters define <cnBoxString> instead of characters
      // holding graphic signs.

      #include "Box.ch"

      PROCEDURE Main
         DispBox( 10,10,20,50, "AbCdEfGhi", "W+/R" )


         DispBox( 10,10,20,50, B_DOUBLE + Space(1) )
         DispOut( "Using #define constant" )

         @ MaxRow(),0


@…BOX, @…CLEAR, @…TO, Scroll(), SetColor()



Checks if the default color is set.


      IsDefColor() --> lIsDefaultColor


The function returns .T. (true) when the default color string is set with SetColor(), otherwise .F. (false) is returned. The default color string is “W/N, N/W, N/N, N/N, N/W”.


IsColor(), SetColor()



Determine if the current computer has color capability


      ISCOLOR() | ISCOLOUR() --> lBoolean


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"
         cBox  = "W+"
         cSays = "W/N, N+/W"
         cGets = "W/N, N/W"
      . <statements>





Define screen colors


      SET COLOR | COLOUR TO [[<standard>]
            [,<enhanced>] [,<border>] [,<background>]
            [,<unselected>]] | (<cColorString>)


<standard> is the color that paints 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> is the color that paints highlighted displays. This includes GETs with INTENSITY ON, the MENU TO, DBEDIT(), and ACHOICE() selection highlight.

<border> is the color that paints the area around the screen that cannot be written to.

<background> is not currently supported by any machines for which Computer Associates provides drivers. This setting is supplied for compatibility purposes only.

<unselected> is a color pair that provides input focus by displaying the current GET in the enhanced color while other GETs are displayed in this color.

<cColorString> is a character string enclosed in parentheses containing the color settings. This facility lets you specify the color settings as an expression in place of a literal string or macro variable.

SET COLOR TO with no argument restores the default colors to W/N, N/W, N, N, N/W.


SET COLOR, a command synonym for the SETCOLOR() function, defines colors for subsequent screen painting activity. Each SET COLOR command specifies a list of color settings for the five types of screen painting activity. Each setting is a foreground and background color pair separated by the slash (/) character. 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 only.

In addition to color, a foreground setting can have an attribute, high intensity or blinking. With a monochrome display, high intensity enhances brightness of painted text. With a color display, high intensity changes the hue of the specified color making it a different 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 a rapid interval. Blinking is denoted with *. An attribute character can occur anywhere in a setting, but is always applied to the foreground color regardless where it occurs.

Each color can be specified using either a letter or a number, but numbers and letters cannot be mixed within a setting. Note that numbers are supplied for compatibility purposes and are not recommended.

All settings are optional. If a setting is skipped, its previous value is retained with only new values set. Skipping a foreground or background color within a setting sets the color to black.

The following colors are supported:

         Color Table
         Color          Letter    Number  Monochrome
         Black          N, Space  0       Black
         Blue           B         1       Underline
         Green          G         2       White
         Cyan           BG        3       White
         Red            R         4       White
         Magenta        RB        5       White
         Brown          GR        6       White
         White          W         7       White
         Gray           N+        8       Black
         Bright Blue    B+        9       Bright Underline
         Bright Green   G+        10      Bright White
         Bright Cyan    BG+       11      Bright White
         Bright Red     R+        12      Bright White
         Bright Magenta RB+       13      Bright White
         Yellow         GR+       14      Bright White
         Bright White   W+        15      Bright White
         Black          U                 Underline
         Inverse Video  I                 Inverse Video
         Blank          X                 Blank

SET COLOR is a compatibility command and is not recommended. It is superseded by the SETCOLOR() function which can return the current color as well as set a new color.


. Monochrome monitors: Color is not supported on monochrome monitors. Clipper, however, supports the monochrome attributes inverse video (I) and underlining (U).

. Screen drivers: SET COLOR TO, using numbers, may not be supported by screen drivers other than the default screen driver.


      .  This example uses the unselected setting to make the current
         GET red on white while the rest are black on white:

          cColor:= "W/N,R/W,,,N/W"
          SET COLOR TO (cColor)
          cOne := cTwo := SPACE(10)
          @ 1, 1 SAY "Enter One: " GET cOne
          @ 2, 1 SAY "Enter Two: " GET cTwo

       .  In this example a user-defined function gets a password from
          the user using the blank (X) enhanced setting to hide the password as
          the user types:

          IF !DialogPassWord(12, 13, "W+/N", "FUNSUN", 3)
             ? "Sorry, your password failed"

          FUNCTION DialogPassWord( nRow, nCol, ;
                 cStandard, cPassword, nTries )
             LOCAL nCount := 1, cColor := SETCOLOR()
             SET COLOR TO (cStandard + ", X")      // Blank input
             DO WHILE nCount < nTries
                cUserEntry:= SPACE(6)
                @ nRow, nCol SAY  "Enter password: " GET ;
                IF LASTKEY() == 27
                   SET COLOR TO (cColor)
                   RETURN .F.

                ELSEIF cUserEntry == cPassword
                   SET COLOR TO (cColor)
                   RETURN .T.
             SET COLOR TO (cColor)
             RETURN .F.





Clear a rectangular region of the screen


       @ <nTop>, <nLeft> [CLEAR
              [TO <nBottom>, <nRight>]]
              [DOUBLE] [COLOR <cColor>]


<nTop> and <nLeft> define the upper-left corner coordinate.

TO <nBottom>, <nRight> defines the lower-right corner coordinates of the screen region to CLEAR. If the TO clause is not specified, these coordinates default to MAXROW() and MAXCOL().


@…CLEAR erases a rectangular region of the screen by filling the specified region with space characters using the current standard color setting. After @…CLEAR erases the designated region, the cursor is located in the upper corner of the region at <nTop> + 1 and <nLeft> + 1. ROW() and COL() are also updated to reflect the new cursor position.


       .  This example erases the screen from 10, 10 to 20, 40, painting
       the region blue and then displaying a bright cyan box on blue:

       @ 10, 10 CLEAR TO 20, 40
       @ 10, 10 TO 20, 40



SP Color Implementation

 This is not the perfect color scheme. It is the one
 this library runs on. The color scheme relates to SuperLib functions,
 and will not affect your other color usage.

 Basically, when a SuperLib metafunction is called, it
 will usually have a main screen, a menu, and a number of popups
 and other attached screens. Rather than have a burned-in color
 set, or use SETCOLOR() as the default, SuperLib has a dynamic
 color scheme, which may be changed and stored by both the
 programmer and the end-user.

 Several global color settings are used by SuperLib
 functions. The settings are accessed and set via a set of
 functions calls, which themselves access a set of STATIC
 variables. The functions are:

   <cSetting> := sls_normcol([cNew])      For normal output
   <cSetting> := sls_normmenu([cNew])     For normal 'menu to'
   <cSetting> := sls_popcol([cNew])       For popup  box colors
   <cSetting> := sls_popmenu([cNew])      For popup box menus
   <cSetting> := sls_frame([cNew])        Frame string
   <nSetting> := sls_shadatt([nNew])      Shadow color attribute
   <nSetting> := sls_shadpos([nNew])      Shadow  position
                 (0,1,3,7,9) to match the numeric keypad
   <lSetting> := sls_xplode([lNew])       Logical - explode

 All colors are of the format "fg/bg,fg/bg,,,fg/bg"

 (fg-foreground bg-background) except for shadow
 attribute, which is numeric.

 By default, a monochrome set of colors is used. You
 may call the function SATTCOLOR() to make the 'color' colors the

 The function SETCOLORS() allows interactive setting
 of these colors. The variables are stored in COLORS.DBF, which
 contains multiple sets of colors.

 You may override the Clipper ISCOLOR() by
 initializing another setting accessed via the function
 SLS_ISCOLOR(), and setting it to True or False. This is helpful
 in instances where ISCOLOR() sees a color card with a monochrome
 monitor, or some such combination.

 If you are upgrading from 2.50 or previous, see
 "Upgrading" in the appendix.




 SLS_POPMENU() A Superlib color setting function

 <cSetting> => Current value of the setting


 Function                   Setting                     Default
 SLS_POPMENU([cNew])        Popup MENU color            'N/W,W/N,,,+W/N'

 [cNew] sets the setting to a new setting
 If [cNew] is passed, the setting is changed and the
 new setting is returned.


  SETCOLOR(sls_POPMENU()  )        // use to setcolor()