Category : Dbase (Clipper, FoxBase, etc) Languages Source Code
Archive : BOXLIB.ZIP
Filename : BOXLIB.DOC
Output of file : BOXLIB.DOC contained in archive : BOXLIB.ZIP
ÚÄÄÄÄÄÄÄÄÄÄÄÄ¿ ÚÄÄÄÄÄÄÄÄÄÄÄÄ¿ ÚÄÄÄÄÄÄÄÄÄÄÄÄ¿
³ 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 :
the top row and left column position of the box.
rows and the width in columns of the box.
used in the Clipper SETCOLOR() function.
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.
in Clipper functions to designate a set of border
characters. The 9th character, known as the fill
character must be supplied.
within the top of the box frame.
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
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 :
representing the row and column offsets from the
top left corner of the box where
appear.
box.
ON INTEREST : If
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 :
representing the row and column offsets from the
top left corner of the box where the elements of
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 :
will be displayed within the box. The length of
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 :
the five ACHOICE() modes as defined in the
Clipper manual.
element number of the currently highlighted item.
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
Very nice! Thank you for this wonderful archive. I wonder why I found it only now. Long live the BBS file archives!
This is so awesome! 😀 I’d be cool if you could download an entire archive of this at once, though.
But one thing that puzzles me is the “mtswslnkmcjklsdlsbdmMICROSOFT” string. There is an article about it here. It is definitely worth a read: http://www.os2museum.com/wp/mtswslnk/