Dec 152017
 
Box-drawing object library for Clipper 5.0. Also includes a text file explaining the use of objects with Clipper.
File BOXLIB.ZIP from The Programmer’s Corner in
Category Dbase Source Code
Box-drawing object library for Clipper 5.0. Also includes a text file explaining the use of objects with Clipper.
File Name File Size Zip Size Zip Type
BOX.PRG 12588 2947 deflated
BOXLIB.CH 1269 466 deflated
BOXLIB.DOC 24412 5283 deflated
BOXLIB.LIB 10263 4000 deflated
BOXLIB.PRG 11274 2138 deflated
CPI.DEK 17722 6846 deflated
CPI.DOC 38738 13749 deflated
CPI.FIX 14448 4950 deflated
PCC.BAT 93 57 deflated
PCL.BAT 72 64 deflated
PCM.BAT 118 75 deflated
SHADOW.C 1693 693 deflated

Download File BOXLIB.ZIP Here

Contents of the BOXLIB.DOC file





BBBBBBB OOOOOO X X
B B O O X X
B B O O X X
BBBBBBB O O XX
B B O O X X
B B O O X X
BBBBBBB OOOOOO X X


The following written documentation is provided for attendees
of the Clipper Developer's Conference
(Oct. 8th - 11th, 1990) in Orlando, Florida

BOXLIB and the accompanying demo program BOX.PRG were written by :

The Leylan Factor Phone : (808) 487-2230
98-626 Moanalua Loop, #201
Aiea, HI 96701-5172 CIS : 74216,3212

The concepts provided here are solid, workable and worthy of
consideration by serious applications developers looking for ways to
maximimize reusability and reduce interdependencies across modules.

The actual methods used, i.e. the reliance on Clipper's preprocessor
to resolve pseudo-object contructs like Box:New, Box:Top, etc. is open
to debate. Personally I like the methodology and have had no problems
using the routines in their present Clipper 5.0 form or in their
previous incarnations in Summer '87. Previous versions however, did
not attempt to emulate the "look & feel" of instance variables.

In my defense I'll point out that most of the criticisms revolve around
issues that are limited to the "object handler" portion of the code and
that the BOX demo does not (or should not) contain direct references to
the pseudo-instance variables (PIV). By limiting the "oddities" to the
BOXLIB program virtually no explanation is necessary for an applications
programmer to make immediate use of the functions provided.

If you have a mind to, I would recommend compiling BOXLIB into an .OBJ
file and using one of the Microsoft or Borland LIB utilities to hide
the inner workings away in a .LIB file.

Importantly no applications code should be written that makes direct
reference to array elements of a box handle. The fact that it is an
array should in fact be forgotten as soon as possible. Circumventing
the front-end gains you nothing and locks all applications code into
a particular version of BOXLIB.



BoxNew()

Purpose : To generate a new instance of class "box".

Syntax : BoxNew(, , , ,
, ,, )

Arguments : and are numeric values representing
the top row and left column position of the box.

and represent the length in
rows and the width in columns of the box.

is a color string of the type normally
used in the Clipper SETCOLOR() function.

is a numeric value which controls the
shadow attribute. A value of one (1) will draw a
shadow while a value of zero (0) will suppress it.

OF INTEREST : Only the values 0 and 1 should be
used to control the shadow display. In addition
to operating as a "flag" the values themselves are
used internally to offset the shadow on the lower,
right-hand side of the box.

is a character string of the type used
in Clipper functions to designate a set of border
characters. The 9th character, known as the fill
character must be supplied.

is a character string which will appear
within the top of the box frame. may be
a null string ("") but must be passed along.

Returns : A "handle". The handle is used to identify which
object you are speaking to. If you lose the handle
you've broken the string between the Dixie cups and
all communication stops.

Example : cColor := "+W/BG,+GR/W,,,+W/BG"
cFrame := " "
cTitle := " Help Box "
bhHelp := BoxNew( 0, 0, 9, 36, ;
cColor, 1, cFrame, cTitle)





BoxTop()

Purpose : To return the top row position of a box.

Syntax : BoxTop(, [])

Arguments : is a handle returned from BoxNew().

is an optional parameter which specifies
a new value for the top row.

Returns : A numeric value. The value represents the current
top row of the specified box. The box does not
need to be on display to use BoxTop().

Example : nTop := BoxTop(bhObject)
nLeft := BoxLeft(bhObject)
@ nTop, nLeft SAY "this messed up my box"
































BoxLeft()

Purpose : To return the left column position of a box.

Syntax : BoxLeft(, [])

Arguments : is a handle returned from BoxNew().

is an optional parameter which specifies
a new value for the left column.

Returns : A numeric value. The value represents the current
left column of the specified box. The box does not
need to be on display to use BoxLeft().

Example : nTop := BoxTop(bhObject)
nLeft := BoxLeft(bhObject)
@ nTop, nLeft SAY "this messed up my box too"
































BoxLength()

Purpose : To return the length of a box.

Syntax : BoxLength(, [])


Arguments : is a handle returned from BoxNew().

is an optional parameter which specifies
a new value for the length.

Returns : A numeric value. The value represents the current
length in rows of the specified box. The box does
not need to be on display to use BoxLength().

Example : cLength := STR( BoxLength(bhObject) )
@ 0, 0 SAY "the length = " + cLength

































BoxWidth()

Purpose : To return the width of a box.

Syntax : BoxWidth(, [])

Arguments : is a handle returned from BoxNew().

is an optional parameter which specifies
a new value for the width.

Returns : A numeric value. The value represents the current
width in columns of the specified box. The box
does not not need to be on display to use
BoxWidth().

Example : cWidth := STR( BoxWidth(bhObject) )
@ 0, 0 SAY "the width = " + cWidth
































BoxColor()

Purpose : To return the color of a box.

Syntax : BoxColor(, [])

Arguments : is a handle returned from BoxNew().

is an optional parameter which specifies
a new value for the color.

Returns : A character string. The string represents the
current color setting of the box and is in the
format used by Clipper's SETCOLOR() function. The
box does not need to be on display to use
BoxColor().

Example : cColor := SETCOLOR( BoxColor(bhObject) )
@ 1, 1 SAY "this is in the box color"
SETCOLOR( cColor )






























BoxShadow()

Purpose : To return the shadow status of a box.

Syntax : BoxShadow(, [])

Arguments : is a handle returned from BoxNew().

is an optional parameter which specifies
a new value for the shadow status.

Returns : A numeric value. The value represents whether or
not there is currently a shadow on the box. A
value of one (1) indicates that there is a shadow
and a value of zero (0) indicates that there is
not. The box does not need to be on display to
use BoxShadow().

Example : IF BoxShadow(bhObject) == 1
@ 0, 0 SAY "I have a shadow"
ELSE
@ 0, 0 SAY "What ... No shadow ?"
ENDIF



























BoxFrame()

Purpose : To return the frame characters of a box.

Syntax : BoxFrame(, [])

Arguments : is a handle returned from BoxNew().

is an optional parameter which specifies
a new value for the frame characters.

Returns : A character string. The string represents the
current characters used to build the border of
the box and is in the format used by Clipper's
@...BOX command. The box does not need to be on
display to use BoxFrame().

OF INTEREST : BoxLib uses the ninth character in
the string (considered optional in Clipper) as
the "fill" character and it should be included.

Example : cFrame := BoxFrame(bhObject)
@ 0, 0 SAY "frame characters = " + cFrame



























BoxTitle()

Purpose : To return the title of a box.

Syntax : BoxTitle(, [])

Arguments : is a handle returned from BoxNew().

is an optional parameter which specifies
a new value for the title.

Returns : A character string. The string represents the
current title as it appears in the frame at the
top of the box and is in the format used by so
many strings in computer languages... ASCII. The
title can be a null string (""). The box does
not need to be on display to use BoxTitle().

OF INTEREST : No processing is done on the title
by the box functions. Both upper and lower case
characters are permitted as well as leading and
trailing spaces and any symbols normally permitted
in text strings.

Example : cTitle := BoxTitle(bhObject)
IF !EMPTY( cTitle )
@ 0, 0 SAY cTitle
ENDIF






















BoxBottom()

Purpose : To return the bottom row of a box.

Syntax : BoxBottom()

Arguments : is a handle returned from BoxNew().

Returns : A numeric value. The value represents the current
bottom row of the specified box. The box does not
need to be on display to use BoxBottom().

OF INTEREST : BoxBottom() is a computed value and
is equal to (BoxTop() + BoxLength() - 1). As such
the value cannot be "set" with the BoxBottom()
function. Adjustments to "bottom" can be achieved
indirectly by adjustments to the top and/or length
values.

Example : cBottom := STR( BoxBottom(bhObject) )
@ 0, 0 SAY "bottom row = " + cBottom





























BoxRight()

Purpose : To return the right column of a box.

Syntax : BoxRight()

Arguments : is a handle returned from BoxNew().

Returns : A numeric value. The value represents the current
right column of the specified box. The box does
not need to be on display to use BoxRight().

OF INTEREST : BoxRight() is a computed value and
is equal to (BoxLeft() + BoxWidth() - 1). As such
the value cannot be "set" with the BoxRight()
function. Adjustments to "right" can be achieved
indirectly by adjustments to the left and/or width
values.

Example : cRight := STR( BoxRight(bhObject) )
@ 0, 0 SAY "right column = " + cRight





























BoxShow()

Purpose : To display a box on the screen.

Syntax : BoxShow()

Arguments : is a handle returned from BoxNew().

OF INTEREST : BoxShow() automatically displays
a box of defined size at the defined position
with the defined color, border and title.

BoxShow() also stores the background image, it's
position and it's size before the box is drawn to
enable restoration of the background even when
the box has been repositioned and resized.

Returns : The box handle

Example : BoxShow(bhObject)






























BoxDrag()

Purpose : To allow repositioning of a box.

Syntax : BoxDrag(, )

Arguments : is a handle returned from BoxNew().

is also a handle returned from the
BoxNew() function which is used as the workspace
within which the primary box may be moved.

Attempts to move beyond the borders of bhDomain
will be prevented.

OF INTEREST : Moving the box is accomplished by
using the four arrow keys as well as the HOME,
END, PG UP and PG DN keys. Pressing the ENTER
key or the ESCAPE key terminates movement.

If the ENTER key is used the positional values
of the box will be updated. If the ESCAPE key is
pressed the values will remain unchanged. As a
result BoxDrag() does not automatically repaint
the box. Responsibility for updating the screen
is left to the applications programmer.

Returns : The box handle

Example : BoxDrag(bhObject, bhDomain)

IF !( LASTKEY() == K_ESC )
BoxUnshow( bhObject )
BoxShow( bhObject )
ENDIF















BoxSize()

Purpose : To allow resizing of a box.

Syntax : BoxSize(, )

Arguments : is a handle returned from BoxNew().

is also a handle returned from the
BoxNew() function which is used as the workspace
within which the primary box may be resized.

Attempts to size beyond the borders of bhDomain
will be prevented. A minimum size of two rows
and two columns is enforced in order to prevent
losing the box.

OF INTEREST : "size" does not reset the values
of the box object nor does it automatically repaint
the box. Both of these responsiblities are left
to the applications programmer.

OF INTEREST : Sizing the box is accomplished by
using the four arrow keys as well as the HOME,
END, PG UP and PG DN keys. Pressing the ENTER
key or the ESCAPE key terminates sizing.

If the ENTER key is used the dimensional values
of the box will be updated. If the ESCAPE key is
pressed the values will remain unchanged. As a
result BoxSize() does not automatically repaint
the box. Responsibility for updating the screen
is left to the applications programmer.

Returns : The box handle

Example : BoxSize(bhObject, bhDomain)

IF !( LASTKEY() == K_ESC )
BoxUnshow( bhObject )
BoxShow( bhObject )
ENDIF








BoxReshow()

Purpose : To refresh the onscreen image of a box.

Syntax : BoxReshow(, )

Arguments : is a handle returned from BoxNew().

is a key word used to indicate the
attribute which should be redrawn it must be
one of the following :

BX_FRAME reshows the frame
BX_TITLE reshows the title

OF INTEREST : Reshowing the frame or title will
not affect text within the box. Other attributes
including text within the box cannot currently be
repainted should that become necessary it remains
the responsibility of the applications programmer.

Returns : The box handle

Example : BoxReshow(bhObject, BX_FRAME)


























BoxSave()

Purpose : To save the current position, size and screen image
of a box.

Syntax : BoxSave()

Arguments : is a handle returned from BoxNew().

OF INTEREST : The BoxSave() function is reserved
for internal use only. It has been declared as a
STATIC function rendering it out of reach to the
applications programmer.

BoxSave() is called by the BoxShow() function to
store the background image, it's position and it's
size before the box is drawn to enable restoration
of the background even when the box has been
repositioned and resized.

Returns : The box handle

Example : Called internally by BoxShow



























BoxUnshow()

Purpose : To restore a screen image saved by a previous call
to BoxShow().

Syntax : BoxUnshow()

Arguments : is a handle returned from BoxNew().

OF INTEREST : Both the position and size of the
image are retained insuring that the screen can be
restored correctly even if the box's current
position and size have been altered.

Returns : The box handle

Example : BoxUnshow(bhObject)

































BoxClear()

Purpose : To clear the area contained within a box.

Syntax : BoxClear()

Arguments : is a handle returned from BoxNew().

OF INTEREST : Clearing a box has no affect on
the box frame.

Returns : The box handle

Example : BoxClear(bhObject)




































BoxSay()

Purpose : To output a string of text to a box.

Syntax : BoxSay(, , ;
, )

Arguments : is a handle returned from BoxNew().

and are numeric values
representing the row and column offsets from the
top left corner of the box where will
appear.

is a character string to be printed in the
box.

ON INTEREST : If is too long to fit within
the box the output is automatically truncated. If
the row or column offset places the string outside
of the box the function call will be ignored.

Returns : The box handle

Example : BoxSay(bhObject, 1, 1, "With any luck at all ")
BoxSay(bhObject, 2, 1, "this is displayed inside")
BoxSay(bhObject, 3, 1, "my box ")























BoxAsay()

Purpose : To output an array of strings of text to a box.

Syntax : BoxAsay(, , ;
, )

Arguments : is a handle returned from BoxNew().

and are numeric values
representing the row and column offsets from the
top left corner of the box where the elements of
will appear.

is an array of character strings to be
printed in the box.

ON INTEREST : If any string in aText is too long
to fit within the box the output of that string
is automatically truncated. If the row or column
offset places the initial string outside of the
visible box the function call will be ignored.

If the length of the array is greater than the
length of the box only the elements which fall
within the box will be displayed.

Returns : The box handle

Example : LOCAL aMsg := { "With any luck at all " ,;
"this is displayed inside" ,;
"my box " }

BoxAsay(bhObject, 1, 1, aMsg)
















BoxPick()

Purpose : To display a picklist of items within a box and
to provide the option to choose one of them.

Syntax : BoxPick(, )

Arguments : is a handle returned from BoxNew().

is an array of character strings which
will be displayed within the box. The length of
, i.e. the number of array elements can
exceed the length of the box. If the number of
items is greater than the number of rows in the
box additional items can be scrolled into view by
using the up and down arrow keys as well as HOME,
END, PG UP and PG DN.

OF INTEREST : The top row and left column offset
positions of the picklist within the box are
fixed. The bottom row and right column however
are adjusted to reflect the size of the box when
"pick" is called.

Returns : A numeric value corresponding to the element
number of the item chosen or zero (0) if no valid
choice was made, i.e. the ESCAPE key was pressed.

Example : LOCAL aMenu := { "Choice One " ,;
"Choice Two " ,;
"Choice Three" }

nKey := BoxPick(bhObject, aMenu)

















BoxPicku()

Purpose : To process keystrokes submitted to Clipper's
ACHOICE() function called from within BoxPick().

Syntax : BoxPicku( , , )

Arguments : is a numeric value representing one of
the five ACHOICE() modes as defined in the
Clipper manual.

is a numeric value representing the
element number of the currently highlighted item.

is a numeric value representing the
relative row position within the box's menu
scrolling area.

OF INTEREST : The BoxPicku() function is reserved
for internal use only.

Returns : An action code for the ACHOICE() function.

Example : Called internally by BoxPick


























 December 15, 2017  Add comments

Leave a Reply