Programmer 7500/MAX_PROGRAMMERS.iso/PASCAL/BUPV100A.ZIP/CHAPT01.TXT

Text File | 1991-09-06 | 17.0 KB | 437 lines

                                                 Chapter 1
                                                 Fast Screen Writing Routines
                                                 The Basner Utilities v1.0a

 "Look In, Look The Storm In The Eye. Look Out To The Sea And The Skies.
  Look In, Look Out, Look Around. Tough Times Demand Tough Talk."
                                        Neal Peart - RUSH



 1.1                                             Fast Screen Writing Routines
------------------------------------------------------------------------------

{ SPECIAL NOTE: The Basner Utilities are currently in beta test mode, so the
                documentation may not be complete on all routines. Please
                refer to the include demo files for any updates to the code. }

INTERFACE

The basFAST unit contains several objects which themselves contain several
powerful screen writing procedures. The objects are:

  SCREENOBJ  : The actual screen writing routines, such as WriteCenter,
               SaveScreen and PartRestoreScreen.

  WINDOWOBJ  : Windowing and box routines.

 1.2                                             Fast Screen Writing Routines
------------------------------------------------------------------------------

IMPLEMENTATION

I..ScreenOBJ - The Fast Screen Writing Methods.

  ScreenOBJ
    CONSTRUCTOR Init;
    FUNCTION    ColorAttr( C1, C2 : byte ): byte;
    FUNCTION    ReadByte( X, Y : byte ): longint;
    PROCEDURE   SetColors( C1, C2 : byte );
    PROCEDURE   WriteByte( X, Y, CA : byte; Txt : char );
    PROCEDURE   WriteAt( X, Y, CA : byte; Txt : string );
    PROCEDURE   WritePlain( X, Y : byte; Txt : string );
    PROCEDURE   WriteBack( X, Y, CA : byte; Txt : string );
    PROCEDURE   WriteBetween( X1, X2, Y, CA : byte; Txt : string );
    PROCEDURE   WriteCenter( Y, CA : byte; Txt : string );
    PROCEDURE   WriteVertical( X, Y, CA : byte; Txt : string );
    PROCEDURE   PartClear( X1, Y1, X2, Y2, CA : Byte; Txt : char );
    PROCEDURE   ClearScreen( CA : byte; Txt : char );
    PROCEDURE   PartSaveScreen( X1, Y1, X2, Y2, ScreenField : byte );
    PROCEDURE   SaveScreen( ScreenField : byte );
    PROCEDURE   PartRestoreScreen( X1, Y1, X2, Y2, ScreenField : byte );
    PROCEDURE   RestoreScreen( ScreenField : byte );
    DESTRUCTOR  Done;
  PRIVATE
    VideoSegment : word;
    NormalTxt : byte;
    Highlited : byte;
    WriteDelay : integer;
    ScreenStorage : array [ 1..cMaxSaveScreens ] of bScreenInfo;



 1.3                                             Fast Screen Writing Routines
------------------------------------------------------------------------------

DEFINITIONS AND USAGE

1..Constructor

  INIT initializes all private and public variables used within the ScreenOBJ
object and sets up all pointers and field arrays.

  EXAMPLE:

    Program DEMIO1;

    Uses Crt, Dos, basFAST;

    begin
      with Screen do begin
        Init; { Initializes the object }
        ClearScreen( ColorAttr( Blue, Black ), '░' );
        WriteCenter( 3, ColorAttr( Yellow, Red ), 'The Basner Utilities v1.0a
                                                   For Turbo Pascal 6.0!' );
      end; { LOOP: Screen }
    end. { PROGRAM: DEMIO1 }

2..Functions

  Within the ScreenOBJ object, there are a few useful functions for returning
information from the object's private variables. These include:

  ColorAttr( Foreground, Background : byte )
              Combines the passed Foreground And Background attribute bytes
              into a single byte usable by the ScreenOBJ object.

    SYNTAX: TempColorByte := ColorAttr( Blue, Red );
            {Sets variable TempColorByte to 20 (bitwise = Blue On Red ).}

            WriteAt( 1, 1, ColorAttr( Yellow, Black ), 'This Is A Test!' );
            {Writes the specified string at screen coordinate 1, 1 using
             a Yellow on Black color scheme.}

  ReadByte( X, Y : byte )
              Reads a byte from screen memory (at the passed X and Y
              coordinates) and returns it in the form of a long integer.


 1.4                                             Fast Screen Writing Routines
------------------------------------------------------------------------------

    SYNTAX: ScreenInfo := ReadByte( 1, 1 );
            {Sets the variable ScreenByte to the combined values of the
            character at screen 1, 1.}

           ScreenChar := chr( lo( ReadByte( 1, 1 )));
           {Sets the variable ScreenChar to the CHARACTER at screen
           position 1, 1.}

3..Procedures

  A..Writing Text To The Screen.

  The power of the ScreenOBJ object's procedures is not to be taken lightly.
Within this object are procedures to allocate and deallocate screen memory.
(which, if used incorrectly, could definitely lockup your PC!) But, fear of
program crashes aside, the procedures are very useful and versatile.
Contained within the object are:

  SetColors( Normal_Text, Hilited_Text : byte )
              Sets the default colors used by ScreenOBJ.

    SYNTAX: SetColors( ColorAttr( Yellow, Black ), ColorAttr( Black, Cyan ));
            {Sets the default normal text color to Yellow on Black and the
            default hilited text color to Black on Cyan.}

  WriteByte( X, Y, Color : byte; Txt : char )
              Writes a character directly to screen memory at position X, Y
              using the specified color scheme.

    SYNTAX: WriteByte( 1, 1, ColorAttr( White, Blue ), 'A' );
            {Puts 'A' at position 1,1 in screen memory using the specified
            color scheme.}


 1.5                                             Fast Screen Writing Routines
------------------------------------------------------------------------------

  WriteAt( X, Y, Color : byte; Txt : string )
              Writes a string directly to screen memory starting at position
              X, Y using the specified color scheme.

    SYNTAX: WriteAt( 1, 1, ColorAttr( White, Black ), 'THE BASNER UTILITIES' );
            {Writes the specified string at position 1, 1 in screen memory
            using the specified color scheme.}

SPECIAL NOTE:
  All descendants of the WriteAt procedure can hilite characters within the
passed string. By placing a ~ to mark the beginning AND then ending of the
hilited text, certain sections of the text may be defined as hilited and will
be printed using the specified hilite color (as per the SetColors procedure).

EXAMPLE:
  with Screen do begin
    Init; { Initialize the object }
    SetColors( ColorAttr( Cyan, Black ), ColorAttr( Black, Red ));
    WritePlain( 1, 1, 'The Basner Utilities Are ~EXCELLENT~! );
   end; { LOOP: Screen }

  {Initializes the object before use. Sets default colors. Then, prints the
  passed string using default colors. The substring 'EXCELLENT' will be printed
  in the default hilite color scheme of Black on Red.}

     WritePlain( X, Y : byte; Txt : string )
              Writes a string directly to screen memory at position X, Y
              using the default color scheme(s).

    SYNTAX: WritePlain( 1, 1, 'These Are The ~Default~ Colors...' );
            {Writes the passed text starting at position 1, 1 in screen
            memory using the default normal and hilited text color schemes.}


 1.6                                             Fast Screen Writing Routines
------------------------------------------------------------------------------

    WriteBack( X, Y, CA : byte; Txt : string )
              Writes text BACKWARD from the end to the beginning of the string,
              so that the first character is at position X, Y, using
              specified color scheme.

              NOTE: There is a default pause of 500 milliseconds (.5 seconds)
                    between each character printed.

    SYNTAX: WriteBack( 41, 1, ColorAttr( White, Black ), 'The Basner Utils!' );
            {Writes the specified string backwards on the screen.}

    WriteBetween( X1, X2, CA : byte; Txt : string )
              Writes a string centered on the screen between positions X1, Y
              and X2, Y using the specified color scheme.

    SYNTAX: WriteBetween( 10, 71, 3, ColorAttr( Yellow, Blue ),
                          ' * The Basner Utilities Version 1.0a * ' );
            {Writes the specified string centered between screen coordinates
            10,3 and 71,3 using the specified color scheme.}

    WriteCenter( Y, CA : byte; Txt : string )
              Writes a string centered in screen row Y using the specified
              color scheme.

    SYNTAX: WriteCenter( 3, ColorAttr( Yellow, Blue ),
                         ' * The Basner Utilities Version 1.0a * ' );
            {Same as the example for WriteBetween, but centers it in row 3
            of the screen's memory using the specified color scheme.}

    WriteVertical( X, Y, CA : byte; Txt : string )
              Writes a string vertically on the screen starting at position
              X, Y using the specified color scheme.


 1.7                                             Fast Screen Writing Routines
------------------------------------------------------------------------------

    SYNTAX: WriteVertical( 1, 1, ColorAttr( LightCyan, Black ),
                           'The Basner Utilities' );
            {EXAMPLE BY DISPLAY}
            T
            h
            e

            B
            a
            s
            n
            e
            r

            U
            t
            i
            l
            i
            t
            i
            e
            s




 1.8                                             Fast Screen Writing Routines
------------------------------------------------------------------------------

    B..Screen Manipulation Routines

  There are a few include routines for saving, restoring and manipulating the
physical screen. Please be sure to use the Init constructor to initialize the
pointers, arrays and constants within the object before using these routines.
Include routines are:

    PartClear( X1, Y1, X2, Y2, CA : byte; Txt : char )
              Clears part of the screen in a box form and fills the screen with
              the specified character in Txt. The box is shaped using position
              X1, Y1 as the upper-left corner and X2, Y2 as the bottom-right
              corner of the box.

    SYNTAX: PartClear( 3, 2, 78, 24, ColorAttr( Blue, Black ), '▓' );
            {Clears a box using the passed coordinates, then filling it with
            '▓' using the specified color scheme.}

    ClearScreen( CA : byte; Txt : char )
              Clears the ENTIRE screen and then fills it with the specified
              character in Txt using the passed color scheme (as per
              PartClear).

    SYNTAX: ClearScreen( ColorAttr( LightBlue, Black ), 'A' );
            {Clears the entire screen and then fills it with 'A' using the
            specified color scheme.}

    PartSaveScreen( X1, Y1, X2, Y2, ScreenField : byte )
              Saves a portion of the screen to a private array within the
              object. The field of the private array is specified by
              ScreenField (min. 1, max. 5 currently).

              NOTE: There is currently an object-defined maximum of 5
                    screens that may be saved within the object.

    SYNTAX: PartSaveScreen( 1, 1, 40, 25, 1 );
            {Saves the portion of the physical screen from 1,1 to 40,25 into
            field 1 of the private array.}


 1.9                                             Fast Screen Writing Routines
------------------------------------------------------------------------------

    SaveScreen( ScreenField : byte )
              This procedure works the same as PartSaveScreen, but instead
              saves the ENTIRE screen off into the private array.

    SYNTAX: SaveScreen( 3 );
            {Saves the entire screen off into the third field of the private
            array for storage of screens.

    PartRestoreScreen( X1, Y1, X2, Y2, ScreenField : byte )
              Partially restores saved information to video memory.

              NOTE: Be sure to only restore saved information to the screen's
                    memory, as uninitialized variables and records contain
                    whatever values were in the memory allocated to them prior
                    to its usage as variable storage!

    SYNTAX: PartRestoreScreen( 2, 2, 79, 24, 1 );
            {Restore the part of the screen previously stored that was within
            coordinates 2,2 and 79,24 in field 1 of the private storage array.}

    RestoreScreen( ScreenField : byte )
              This procedure works the same as PartRestoreScreen, but restores
              ALL information for the saved video screen.

    SYNTAX: RestoreScreen( 5 );
            {Restores all screen information stored in array 5 of the
            private storage array to the physical screen.}


 1.10                                            Fast Screen Writing Routines
------------------------------------------------------------------------------

4..Destructor

  Finally, the destructor for ScreenOBJ, Done, deallocates all allocated
memory that was used for the object's methods and variables.

    Done
              Deallocates memory.

    SYNTAX: Done;


 1.11                                            Fast Screen Writing Routines
------------------------------------------------------------------------------

II..WindowOBJ - The Windowing Methods.

  WindowOBJ = object
    CONSTRUCTOR Init;
    PROCEDURE   Box( X1, Y1, X2, Y2, CA, BType : byte );
    PROCEDURE   FillBox( X1, Y1, X2, Y2, CA, BType : byte );
    PROCEDURE   ShadowBox( X1, Y1, X2, Y2, CA, BType : byte );
    PROCEDURE   ExplodeBox( X1, Y1, X2, Y2, CA, BType : byte );
    PROCEDURE   ShadowExplodeBox( X1, Y1, X2, Y2, CA, BType : byte );
    DESTRUCTOR  Done;
  end;


 1.12                                            Fast Screen Writing Routines
------------------------------------------------------------------------------

DEFINITIONS AND USAGE

1..Constructor

    Init
              Allocates memory for the WindowOBJ object's private variables
              and methods. This routine MUST be called in order to properly
              use the object's procedures!

    SYNTAX: Init;

2..Procedures

  Within the WindowOBJ object, there are several different forms of boxes
(ie, windows) that can be called, ranging from unfilled outlines to exploding,
shadowed boxes. The box types are:

##  Box Type
-------------------------------------------------
1   No Box Characters
2   Single Line Box
3   Double Line Box
4   Single Line Horizontal, Double Line Vertical
5   Double Line Horizontal, Single Line Vertical

These include:

    Box( X1, Y1, X2, Y2, CA, BType : byte )
              Creates only the outline of a window in video memory using the
              specified color scheme. This method does not fill the interior
              of the box.

    SYNTAX: Box( 2, 2, 40, 15, ColorAttr( White, Black ), 3 );
            {Draws a double lined box using position 2,2 as the upper-left
            corner and 40,15 as the bottom right corner using the specified
            color scheme.}

    FillBox( X1, Y1, X2, Y2, CA, BType : byte );
              Creates a box, as per Box, but fills the interior of the box
              with spaces using the specified color scheme.


 1.13                                            Fast Screen Writing Routines
------------------------------------------------------------------------------

    SYNTAX: FillBox( 2, 10, 79, 24, ColorAttr( Yellow, Blue ), 1 );
            {Draws a single lined box, like Box, and fills the interior with
            spaces of the specified color scheme.}

    ShadowBox( X1, Y1, X2, Y2, CA, BType : byte )
              Similar to FillBox, ShadowBox creates a filled box of type
              BType, and then shades the bottom and right side of the box to
              create a 3dimensional feel to the box. The shading uses the
              characters in screen memory along the "shadowed" edges of the
              box and puts a darkening color scheme to it to create the
              feeling of 3 dimensions.

    SYNTAX: ShadowBox( 5, 3, 76, 23, ColorAttr( Yellow, Blue ), 4 );

    ExplodeBox( X1, Y1, X2, Y2, CA, BType : byte );
              Explodes a filled box from the center of the box's area outward
              to its determined corners using the specified color scheme.

    SYNTAX: ExplodeBox( 2, 2, 79, 24, ColorAttr( Black, Red ), 2 );

    ShadowExplodeBox( X1, Y1, X2, Y2, CA, BType : byte );
              Similar to ExplodeBox, ShadowExplodeBox creates a growing box
              and shades the finished box to create the 3dimensional feel.

    SYNTAX: ShadowExplodeBox( 2, 2, 79, 24, ColorAttr( Black, Red ), 2 );

3..Destructor

    Done
              Deallocates memory reserved for the WindowOBJ object.

    SYNTAX: Done;

END. { DOCUMENTATION: Chapter 1 }