Functions and Directives

Function DispBox() Foundation

Displays a box on the screen.

Syntax
DispBox( <nTop>, <nLeft>, <nBottom>, <nRight>, ;
        [<cnBoxString>] , [<cColor>] )  --> NIL
Parameters
<nTop>
<nTop> is an integer numeric value specifying the upper screen row for the box display. The four arguments <nTop>, <nLeft>, <nBottom> and <nRight> indicate the screen coordinates of the box.
<nLeft>
<nLeft> is an integer numeric value which specifies the left screen column for the box display.
<nBottom>
<nBottom> is an integer numeric value which specifies the lower screen row for the box display. When <nBottom> is greater than MaxRow(), the lower row is not visible because output is outside of the screen area.
<nRight>
<nRight> is an integer numeric value which specifies the right screen column for the box display. When <nRight> is greater than MaxCol(), the right column is not visible because output is outside the screen area.
<cnBoxString>
<cnBoxString> determines the characters used to display the border of the box. The expression can be numeric or character data type. With a numeric expression, the value 1 outputs a single line box and the value 2 a double line box. All other numeric values also result in a single line. If <cnBoxString> is a character expression, it defines the characters with which the box is displayed. It is generally a character string of nine characters. The first eight characters define the border of the box and with the ninth character is used to fill the box. Specifying <cnBoxString> is optional. If this argument is omitted, the default is a box drawn with a single line.
<cColor>
The optional argument <cColor> defines the color used to display the box. If this argument is missing, the box is drawn in the default color of the current system colors defined with SetColor().
Return

The return value of DispBox() is always NIL.

Description

The screen function DispBox() displays a box with the specified coordinates, color and border characters. The border is defined by <cnBoxString>. When the argument contains a character string, the first eight characters are used to display the border. The first character defines the upper left corner of the box, the following characters define the border sides and corners in a clockwise direction. The box is filled with the ninth character. When the ninth character is not specified, only the border of the box is output and the screen area within the box remains unchanged.

The function DispBox() sets the cursor to the position <nTop>+ 1and <nLeft>+ 1. Row() and Col() return this new values for the cursor position.

In the file Box.ch (in the directory \XPP\INCLUDE) various constants for the border of a box are defined. Note that an appropriate system font must be installed for the graphic characters of a box border to be displayed correctly.

Examples
DispBox()
// The example displays four boxes showing 
// various possibilities for DispBox() 

#include "Box.ch" 

PROCEDURE Main 
   LOCAL cBox 
   CLS 

   DispBox(7,10,17,60,1)                // single line box in 
   Inkey(0)                             // default system color 

   DispBox(7,10,17,60,2,"W+/B")         // double line in bright 
   Inkey(0)                             // white on blue background 

   cBox := B_SINGLE 
   @ 9,11 SAY "Output before DispBox()" // single line with 
   DispBox(7,10,17,60,cBox)             // no fill character 

   @ Row(),Col() SAY "Output after DispBox(). Box string: " + cBox 
   Inkey(0) 

   cBox := B_DOUBLE + Chr(176) 
   @ 9,11 SAY "Output before DispBox()" // double line with 
   DispBox(7,10,17,60,cBox,"N/BG")      // fill character 

   @ Row(),Col() SAY "Output after DispBox(). Box string: " + cBox 
   Inkey(0) 

RETURN 

Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.