Power-Programmierung/CD1.mdf/pascal/library/dos/wct/xcrt.doc

Text File | 1992-01-18 | 11.3 KB | 304 lines

Here is a fairly more descriptive list of the procedures & functions in my
XCRT unit.

--

procedure beep(hz,dur: word);

This procedure will play a note (in hertz) for a duration of dur
milliseconds. Usually beep(1000,100) is a good high-pitched, error tone.

procedure disablespeaker;
procedure enablespeaker;

I don't think you'll need to use these two.

--

function getch(x,y: byte):char;

Returns the character at position (x,y)

function getattr(x,y: byte):byte;

Returns the color attribute at (x,y). You will see a lot about color
attributes in this unit, so I will explain them now. Background colors may
be 0-7, foreground colors may be 0-15. Blinking is either 0 (off) or 1
(on). The color attribute is set as follows:

blink*128+background*16+foreground

For example, if you wanted to extract the foreground color from a color
attribute at (x,y), that's forecol:=getattr(x,y) div 16.

procedure putch(x,y: byte; c: char);

Puts character c at position x,y. You might wonder if it uses the current
color settings or not. This depends on the unit variable PreserveAttr
(preserve attribute). When PreserveAttr is TRUE, any routine that puts
characters to the screen keeps the same color attribute that is already
there. When PreserveAttr is FALSE, it uses the current color settings.

procedure putattr(x,y:byte; attr:byte);

This procedure sets the color attribute at (x,y). You might wonder why this
is useful. See AttrBlock for a demonstration.

function shadowattr(attr:byte):byte;

This procedure returns the proper shadowing attribute for a color
attribute. This is useful for making windows with shadows. See ShadowBlock
for a demonstration.

--

procedure writexy(x,y: byte; s: writexystring);

This writes a string (s), right-justified, to (x,y). Much easier than
gotoxy(x,y); write(s);

procedure rightjust(x,y: byte; s: writexystring);

This right-justifies a string s at (x,y)

procedure centerjust(x,y:byte; s:writexystring);

This centers a string s about (x,y)

--

procedure textbox(x1,y1,x2,y2: word; border:byte);

This procedure draws a textbox with the corners (x1,y1) and (x2,y2) with a
bordertype of border. See the borders listed in the CONST section of XCRT.
For example, if you wanted to put a box around the entire screen of double
thickness, textbox(1,1,80,25,doubleborder) is what you want.

procedure textline(startat,endat,c:word; attr:byte);

This draws a line between two points. If the line is horizontal, startat
and endat are the two x values and c is the constant y. If the line is
vertical, startat and endat are the two y values and x is the constant x.
Attr is the type of line - again, see the line types in the CONST section.

--

procedure colorblock(x1,y1,x2,y2: word; c:byte);

This procedure fills a block with a solid character of the current
foreground color.

procedure fillblock(x1,y1,x2,y2:word; ch:char);

Fills a region with the specified character. This is useful step #1 in
drawing windows. For example, if we wanted to draw a window with a box
around it from (3,3) to (10,7), here is some code to do it:

textattr:=red*16+yellow; { another way of setting colors at same time }
fillblock(3,3,10,7,' ');
textbox(3,3,10,7,singleborder);

procedure shadowblock(x1,y1,x2,y2:word);

This procedure shadows a region. To extend the above example, if we want to
shadow what's underneath it, you add the line shadowblock(4,4,10,8) before
the FillBlock. Even better would be shadowblock(5,3,11,8) because the
characters are much taller than they are wide. The function shadowattr is
also available if you want to write your own shadowing routines in your
programs.

procedure attrblock(x1,y1,x2,y2:word; attr:byte);

Sets the color attributes for an entire region of the screen. This can be
incredibly useful when used in conjunction with PreserveAttr. For example,
you are writing a program in which there are specific areas that always use
the same color settings. The top line is always white on red. The left is
always lightgray on black. The right is always cyan on blue, and the bottom
line is always yellow on magneta. Admittedly, these may be horrible color
settings, but it's only an example... You will also be constantly writing
things all over the screen. It becomes a big pain in the butt to constantly
keep setting textattr every time you are writing on the screen. Remember,
though, that if PreserveAttr is set to TRUE, it ignores the current
TextAttr setting and preserves the color attributes for where you are
writing. You can take advantage of this fact by setting the color
attributes for regions of the screen ONCE at the beginning of the program,
set PreserveAttr to TRUE (it's defaulted to FALSE), and you're all set. For
our example, that would accomplished as follows:

attrblock(1,1,80,1,red*16+white); { top line }
attrblock(1,2,40,24,black*16+lightgray); { left }
attrblock(41,2,80,24,blue*16+cyan); { right }
attrblock(1,25,80,25,magenta*16+yellow); { bottom }

procedure scrollblockup(x1,y1,x2,y2,wakeattr:byte);
procedure scrollblockdown(x1,y1,x2,y2,wakeattr:byte);

Scrolls a region of the screen up or down one row. When it scrolls, though,
it loses a line from the end, and often you want that line replaced by
something. You can set WakeAttr to tell it what color setting to leave in
place of the last line that was scrolled.

procedure explodeblock(x1,y1,x2,y2:byte);

This draws a block just like fillblock(x1,y1,x2,y2,' ') except that it
draws it so it looks like it's blowing up from the middle. It looks cool
the first few times you use it, then it gets annoying.

--

function readallkeys:char;

This returns ANY key that you pressed. See the unit KEYDEF for the names of
all the "special" keys, like F1, enter, esc, insert, delete, backspace,
CTRL-F4, etc. Ch:=readallkeys will return the key that was pressed.

function yesorno:char;

Since so many programs use a repeat-until to answer this common question, I
made it a function returning 'Y' or 'N'. It does not output or return lower
case.

function getoneof(s:getoneofstring):char;

This extremely handy procedure is good for getting one or several specific
keys but not accepting any others. For example, upcase(getoneof('YyNn')) is
the same thing as YesOrNo. Or something more useful, say you want to wait
for the user to push ENTER, ESC, F1, F2, or any number,
getoneof(enter+esc+f1+f2+'0123456789') is the correct command. It simply
gets characters until the character is contained in the string you sent in.

--

function getcursor:word;

Returns the current cursor setting.

procedure setcursor(curs:word);

Sets the cursor. Setcursor(cursorunderline) makes the cursor the normal
underscore. Setcursor(cursorhalfblock) makes the cursor a sort of square.
Setcursor(cursorblock) makes the cursor a large rectangle.
Setcursor(cursoroff) turns the cursor off.

--

procedure writewindow(fn: string; var w: block);

Writes a "window" to disk.

procedure readwindow(fn: string; var w: block);

Reads a window from disk.

procedure savewindow(x1,y1,x2,y2: word; var w: block);

Saves a portion of the screen into what is known as a block. In the example
about drawing windows with a shadow, we overlooked one very important
detail. You lose whatever is underneath the window you draw. You need to
save that region, draw over it, the restore it when you're done. So, first
to save it... savewindow(3,3,11,8,w). Block is a type in the unit. A block
is basically a rectangular region of a screen (in CRT mode). You usually do
not access the fields of a block. A window is composed of a block, but it
also contains the number of rows and columns. It is used only as a whole
entity. Modifying the fields of a block can have fatal results. Now you are
free to draw your window, and you recall it when necessary.

procedure killwindow(var w:block);

SaveWindow uses memory from the heap to store the block. A block should be
disposed of when possible. So after you restore the screen underneath (see
example after RecallWindow), you should kill the window with killwindow(w).

NOTE: DO NOT kill a window that 1. hasn't been created with a savewindow or
2. has been killed previously. It WILL crash your program.

procedure drawstrip(w:block; x1,y1:byte; row:byte; x2,x3:byte);

Draws a horizontal strip (at y-coorindate row, with x limits x2-x3) of a
block (w) with upper-left hand corner x1,y1.  This is the basis for all of
the other fancy ways of drawing a window.  For example, RecallWindow can
be written as:

for i:=<y1> to <y1>+w.rows-1 do
  drawstrip(w,<x1>,<y1>,i,<x1>,<x1>+w.cols-1)

The others are fairly more complicated.  With a little effort, you can
create all sorts of ways to redraw windows.

procedure recallwindow(x1,y1:word; var w: block);

Recalls a block to the screen. It recalls it with the upper-left hand
corner at (x1,y1). You can use this to make multiple copies of an image if
you wish. Now let's put the entire example we've been compiling together.

{ save screen }
savewindow(3,3,12,8,w);
{ draw window }
shadowblock(5,4,12,8);  { Draws "shadow" underneath window }
textattr:=red*16+white; (* PreserveAttr is FALSE *)
fillblock(3,3,10,7,' ');
textbox(3,3,10,7,singleborder);
(* Do whatever you need to do inside the window *)
{ restore screen }
recallwindow(3,3,w);
{ deallocate memory used by w }
killwindow(w);

procedure explodewindow(x1,y1: byte; w: block);

Very similar to RecallWindow, except that it explodes the window instead of
simply drawing it.  It basically draws it from the inside-out.  It's best
illustrated by trying it out.

procedure crunchwindow(x1,y1: byte; w: block);

The opposite of ExplodeWindow, CrunchWindow draws a window from the
outside-in.

Here's how SaveWindow, WriteWindow, ReadWindow, ExplodeWindow, and
CrunchWindow can all be used to make a software package look very
professional.  Say you have a program with some complex pop-up windows.
Here's what you do:

1. In a separate program, design the pop-up window, capture it
   (SaveWindow), and write it to disk (WriteWindow).
2. In the main program, read the window in (ReadWindow).  Now you can
   display it at will.  Your program isn't bogged down with holding the
   details of how the pop-up window was drawn.
3. When you are ready to display the pop-up, save the area where the pop-up
   will be displayed into another block (SaveWindow).  Then display the
   pop-up using ExplodeWindow.  When you are ready to restore the original
   portion of the screen, draw the original portion using CrunchWindow.  I
   think you'll be pleased with the results.  If it's too fast for you to
   see, try setting ExplodeSteps higher before the entire process.  You can
   reset it once you see the effect.

--

function getfont:byte;
procedure setfont(font:byte);

Ignore these.

--

function getvideomode:byte; procedure setvideomode(mode:byte);

Ignore these too.

--

procedure xcrtinit;

While you're at it, ignore this as well. For some reason, I had to put this
in the interface section. You shouldn't use in the program at all. It could
likely screw things up.


A few words from the author...

This unit can save you tremendous amounts of time by reducing what was
before a tedious chore to a mere one or two lines. I would recommend highly
to anyone who intends to do any more work with Pascal to keep this unit! It
makes life infinitely simpler.