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 }