home *** CD-ROM | disk | FTP | other *** search
/ Frostbyte's 1980s DOS Shareware Collection / floppyshareware.zip / floppyshareware / GLEN / TOTDOC.ZIP / CHAPT5.TXT < prev    next >
Text File  |  1991-02-11  |  48KB  |  1,188 lines
  1.                                                                          Writing
  2.                                                                           to the
  3.                                                                           Screen
  4.  
  5.  
  6.  
  7.          "Some of the newer computer-related equipment is of considerable
  8.          help... Among the most useful tools is the cathode-ray-tube console, a
  9.          computer-connected instrument resembling a television set, which can
  10.          display on its screen textual information from the computer's memory in
  11.          easily readable form."
  12.  
  13.                                           The American Heritage Dictionary, 1981
  14.  
  15.          Most programs need to write output to the display, and usually this
  16.          needs to be done very quickly! The totFAST unit includes a variety of
  17.          objects for writing to the screen.
  18.  
  19.          The main object ScreenOBJ is capable of writing to the physical screen
  20.          as well as virtual screens. A virtual screen is a screen that is not
  21.          visible but provides all the facilities of the physical screen. A vir-
  22.          tual screen can be used to keep a snapshot copy of the physical screen
  23.          so that it may be restored at some later date. Virtual screens can also
  24.          be used to prepare full screen displays "off line", which, when
  25.          required, can be pushed onto the visible screen using a variety of
  26.          effects.
  27.          The ScreenOBJ object provides methods for writing to the screen using
  28.          varied justification, as well as methods to draw lines and boxes, read
  29.          information from the screen, move blocks of text around the screen, and
  30.          control cursor location and appearance.
  31.  
  32.          The totFAST unit also includes objects for controlling the appearance
  33.          of scroll bars and window shadows. Note: remember that the display
  34.          colors are always specified as the composite foreground and background
  35.          attribute (refer to page 3.11 for more information).
  36.  
  37.  
  38. The Writing Engine
  39.          Before plunging into the totFAST unit, you ought to be aware of an
  40.          important Toolkit feature.
  41.  
  42.          At the heart of the ScreenOBJ object is another object called WriteOBJ
  43.          (yes, an object within an object). This object is the screen writing
  44.          engine, and performs all of the primary screen manipulation tasks.
  45.          There are methods for writing text, controlling the cursor, and for
  46.          making direct video memory moves.
  47.          You should never need to access the WriteOBJ methods; when you make
  48.          calls to the ScreenOBJ methods, the Toolkit makes calls to the WriteOBJ
  49.          engine. Ordinarily, therefore, you don't even need to be aware that
  50.          WriteOBJ exists. However, if you want to use some different routines
  51.          for accessing the display (e.g. you want to run programs on non-
  52.  
  53. 5-2                                                                 User's Guide
  54. --------------------------------------------------------------------------------
  55.  
  56.          standard hardware, or you want to run in graphics mode), then all you
  57.          have to do is create your own WriteOBJ-type object, and instruct the
  58.          Toolkit to use it. This "back door" gives you complete control of the
  59.          Toolkit's engine. This feature allows you to modify the Toolkit display
  60.          engine without making a single change to the Toolkit source code.
  61.  
  62.          This whole subject is discussed in detail in Part 2: Extending the
  63.          Toolkit.
  64.  
  65.  
  66. Managing the Visible Screen
  67.  
  68.          One of the few parts of the Toolkit written in Assembler is the screen
  69.          writing code. The reason? Speed. The totFAST unit provides very high
  70.          performance screen writing, especially in CGA systems, which are noto-
  71.          rious for "snow" and slow speeds.
  72.          The Toolkit can write to all PC monitor types ranging from monochrome
  73.          to VGA. For performance reasons, totFAST bypasses DOS screen writing
  74.          services (BIOS) and writes directly to the video area of memory.
  75.  
  76.          The Toolkit automatically switches off the mouse cursor during screen
  77.          writes.
  78.  
  79.  
  80. Using SCREEN
  81.          totFAST includes a global object SCREEN of type ScreenOBJ. SCREEN is
  82.          automatically initialized when you use the totFAST unit. All direct
  83.          screen writing should be performed using the SCREEN instance. For exam-
  84.          ple, to write "Hello World" at the current cursor position, you would
  85.          call the method Write as follows:
  86.  
  87.                   Screen.Write("Hello World");
  88.  
  89.          Most of the other screen writing methods must be passed the X and Y
  90.          coordinates where the string is to be written. Like Turbo Pascal, the
  91.          Toolkit uses a one-based system where the top left of the screen is at
  92.          coordinates (1,1) and the bottom right of the screen is normally
  93.          (80,25). Some routines, like the box drawing methods, need to be passed
  94.          a pair of coordinates. Pass the upper-left and lower-right coordinates,
  95.          respectively.
  96.  
  97.  
  98.  
  99.  
  100. Basic Screen Writing
  101.  
  102.          This section explains how to use the methods for writing strings using
  103.          varied justification methods, how to clear all or part of the screen,
  104.          how to change the display attributes and how to draw lines and boxes.
  105.  
  106.  
  107. Writing to the Screen                                                        5-3
  108. --------------------------------------------------------------------------------
  109.  
  110.             Note: unfortunately, Turbo Pascal provides no facility for writing
  111.             procedures or functions which can be passed different parameter
  112.             types or varying numbers of parameters. For this reason, the Tool-
  113.             kit is incapable of providing the ultra-flexible facilities similar
  114.             to Turbo Pascal's own Write and WriteLn procedures.
  115.  
  116.             The Toolkit therefore expects a single string to be passed to its
  117.             main screen writing methods. If you need to write a non-string
  118.             item, you can use one of the string conversion functions in the
  119.             totSTR unit. For example, to display the value of a real variable
  120.             REALVAL, use the following statement:
  121.  
  122.                      SCREEN.Write(RealToStr(REALVAL));
  123.  
  124.             For plain screen writing, feel free to use Turbo Pascal's proce-
  125.             dures Write and WriteLn, e.g. Write(REALVAL);, but remember to hide
  126.             the mouse first.
  127.  
  128.  
  129.  
  130. Writing Strings
  131.  
  132.          The following eleven methods simplify the tasks of writing strings to
  133.          the screen:
  134.  
  135.          Write(Str:string);
  136.  
  137.          Writes a string at the current cursor position using the default dis-
  138.          play attributes. The display attributes are set with Turbo Pascal's CRT
  139.          procedures TextColor and TextBackground. The cursor is automatically
  140.          moved to the position following the last character of the string.
  141.  
  142.          WriteLn(Str:string);
  143.  
  144.          This method is the same as Write, except that the cursor is moved to
  145.          the beginning of the next line. If the string is written to the last
  146.          line of the display (or the last line of a window - discussed later),
  147.          the display scrolls up one line.
  148.  
  149.          WriteAT(X,Y,Attr:byte; Str:string);
  150.  
  151.          Writes a string at the specified X and Y coordinates using the display
  152.          attribute Attr. The cursor is not moved.
  153.  
  154.          WriteHi(X,Y,AttrHi,Attr:byte; Str:string);
  155.  
  156.  
  157.  
  158. 5-4                                                                 User's Guide
  159. --------------------------------------------------------------------------------
  160.  
  161.          This method is used to write a string with a combination of color
  162.          attributes. Some parts of the string may be written in attribute
  163.          AttrHi, and other parts in Attr. A special character must be embedded
  164.          into the string to indicate when to change attributes. By default, this
  165.          character is '~'. Any text written up to the first occurrence of '~' is
  166.          written using Attr, the next set of text is written in AttrHi. If
  167.          another '~' is encountered, the attribute is switched back to Attr, and
  168.          so on.
  169.  
  170.          For example, the following statement would write the string 'F1 Help'
  171.          so that the 'F1' is highlighted:
  172.                   Screen.WriteHi(1,1,yellow,white,'~F1~ Help');
  173.  
  174.          Similarly, the following statement would write the text so that the
  175.          letter H is highlighted:
  176.                   Screen.WriteHi(1,1,yellow,white,'F1 ~H~elp');
  177.  
  178.          The method SetHiMarker can be used to instruct the Toolkit to recognize
  179.          a different special character. For example, the following statement
  180.          would change the special character to an asterisk:
  181.                   Screen.SetHiMarker('*');
  182.                   Screen.WriteHi(1,1,yellow,white,'F1 *H*elp');
  183.  
  184.  
  185.          WriteCap(X,Y,AttrCap,Attr:byte; Str:string);
  186.          WriteCap is similar to WriteHi. The only difference is that there are
  187.          no embedded markers in the string; WriteCap automatically highlights
  188.          the first capital letter.
  189.  
  190.  
  191.          WriteClick(X,Y,Attr:byte; Str:string);
  192.          This method is the functional equivalent of WriteAT. WriteClick, how-
  193.          ever, causes the PC speaker to emit a "click" after each character is
  194.          written, and the text expands onto the screen from left to right.
  195.  
  196.  
  197.          WriteCenter(Y,Attr:byte; Str:string);
  198.          WriteCenter is ideal for titles and headings. The string is automati-
  199.          cally displayed at the center of the specified line. There is no need
  200.          to compute the X coordinate based on the length of the string, as this
  201.          is all done automatically.
  202.  
  203.  
  204.          WriteBetween(X1,X2,Y1,Attr:byte; Str:string);
  205.          This method writes the string centered between two X coordinates. If
  206.          the text is too long to fit between the coordinates, the full string is
  207.          written starting at X1.
  208.  
  209.  
  210.  
  211. Writing to the Screen                                                        5-5
  212. --------------------------------------------------------------------------------
  213.  
  214.          WriteRight(X,Y,Attr:byte; Str:string);
  215.  
  216.          WriteAT writes the text left-justified at the X coordinate. This
  217.          method, WriteRight, writes the text right-justified at the X coordi-
  218.          nate. The last character of the string will be positioned at (X,Y).
  219.  
  220.          WriteVert(X,Y,Attr:byte; Str:string);
  221.  
  222.          This method writes the string in a vertical column starting at (X,Y),
  223.          i.e. the second character will be drawn at coordinates (X,Y+1), and so
  224.          on.
  225.  
  226.          WritePlain(X,Y:byte; Str:string);
  227.  
  228.          Whereas Write and Writeln use the default attributes, and all the other
  229.          methods are passed the display attribute(s), WritePlain uses the exis-
  230.          ting color attributes at the location where the string is written.
  231.          Because the display attributes are not modified, this is the fastest
  232.          screen writing routine in the Toolkit.
  233.          Listed below is the demo program DEMWR1.PAS and a screen shot of the
  234.          resultant output.
  235.  
  236.  
  237. Figure 5.1                                                              [SCREEN]
  238. The Screen Writing
  239. Methods
  240.  
  241.  
  242.          Program DemoWriteOne;
  243.          {DEMWR1}
  244.  
  245.          USES DOS,CRT, totFAST;
  246.          begin
  247.             ClrScr;
  248.             with Screen do
  249.             begin
  250.                WriteCenter(1,attr(white,red),'TechnoJock''s Object Toolkit');
  251.                WriteCenter(2,79,'Write Demo One');
  252.                WriteAT(5,5,lightgreen,'Written using WriteAT');
  253.                WriteHi(5,7,white,cyan,'Written with the Write~Hi~ method');
  254.                WriteRight(80,9,yellow,'Written with WriteRight');
  255.                WriteCap(5,11,white,cyan,'Written with WriteCap');
  256.                WriteCap(5,13,white,cyan,'also written with WriteCap');
  257.                WriteVert(40,5,12,'Writevert');
  258.                WriteBetween(1,40,15,lightgreen,'Left Half');
  259.                WriteBetween(41,80,15,lightgreen,'Right Half');
  260.                WritePlain(5,17,'This is written with WritePlain');
  261.                GotoXY(5,19);
  262.  
  263.  
  264.  
  265. 5-6                                                                 User's Guide
  266. --------------------------------------------------------------------------------
  267.  
  268.                Write('Good Old Write! ');
  269.                Writeln('And ...');
  270.                Writeln('Good old Writeln');
  271.                Writeln('');
  272.                System.Writeln('This ','is',' Turbo''s Writeln');
  273.                WriteClick(33,24,white,'That''s all Folks!');
  274.                GotoXY(1,25);
  275.             end;
  276.          end.
  277.  
  278.  
  279.  
  280.  
  281. Clearing the Screen
  282.          In addition to Turbo's ClrScr function, the Toolkit provides the fol-
  283.          lowing screen clearing methods in ScreenOBJ:
  284.  
  285.  
  286.  
  287.          Clear(Attr:byte; Ch:char);
  288.  
  289.          This method erases the entire screen and fills the screen with the
  290.          character Ch, using the specified attribute.
  291.  
  292.          PartClear(X1,Y1,X2,Y2,Attr:byte; Ch:char);
  293.  
  294.          This method is similar to Clear, except that only the rectangular area
  295.          between (X1,Y1) and (X2,Y2) is cleared.
  296.  
  297.          ClearText(X1,Y1,X2,Y2:byte);
  298.  
  299.          The method ClearText erases all the characters in the specified region,
  300.          but does not change the display attribute.
  301.  
  302.  
  303. Changing Display Attributes
  304.  
  305.          The ScreenOBJ object includes the following method, Attrib, for chang-
  306.          ing the display attribute of a rectangular area of the screen:
  307.  
  308.          Attrib(X1,Y1,X2,Y2,Attr:byte);
  309.  
  310.          Changes the display in the region between coordinates (X1,Y1) to
  311.          (X2,Y2) to the specified attribute. The displayed characters in this
  312.          region are unscathed except for their color being changed.
  313.  
  314.  
  315.  
  316. Writing to the Screen                                                        5-7
  317. --------------------------------------------------------------------------------
  318.  
  319. Drawing Lines and Boxes
  320.  
  321.          ScreenOBJ includes a host of methods for drawing lines and boxes. The
  322.          boxes may optionally have left, center or right justified title posi-
  323.          tion at the top, bottom, or in a drop box.
  324.          Using the standard (upper ASCII) characters, lines may be drawn using
  325.          either a single or double line. Each line drawing method requires a
  326.          style parameter, of type byte. A style of 1 indicates a single line,
  327.          and 2 a double line. When drawing boxes, the following styles should be
  328.          used:
  329.  
  330.               0     no box border
  331.               1     single line box
  332.               2     double line box
  333.               3     double sides, single top and bottom
  334.               4     single sides, double top and bottom
  335.               5     single left and upper, double lower and right
  336.               6     menu box style
  337.          If a style value of 7 or greater is specified, the lines are drawn
  338.          using the ASCII character represented by the style value. Figure 5.2
  339.          graphically illustrates the impact of the style parameter, and was
  340.          generated from the file DEMBX1.PAS.
  341.  
  342.  
  343. Drawing Boxes
  344.  
  345.          The following three methods are included in the ScreenOBJ:
  346.  
  347.          Box(X1,Y1,X2,Y2,attr,style:byte);
  348.  
  349.          This method draws a rectangular box from (X1,Y1) to (X2,Y2) in the
  350.          specified attribute and style. Only the box border is drawn -- the area
  351.          within the box perimeter is not affected.
  352.  
  353.  
  354. Figure 5.2                                                              [SCREEN]
  355. Line Drawing Styles
  356.  
  357.          FillBox(X1,Y1,X2,Y2,attr,style:byte);
  358.  
  359.          This method is the same as Box, except that the interior of the box is
  360.          erased (or filled).
  361.  
  362.          ShadFillBox(X1,Y1,X2,Y2,attr,style:byte);
  363.  
  364.          This method is the same as FillBox, except that a shadow is also drawn.
  365.          The shadow characteristics are defined with the global instance Shadow-
  366.          TOT^ (see page 3-12).
  367.  
  368.  
  369. 5-8                                                                 User's Guide
  370. --------------------------------------------------------------------------------
  371.  
  372. Boxes with Titles
  373.  
  374.          Often times, you will want to add a title to the box. The method Title-
  375.          Box will draw a filled box with a title. The syntax of the method is as
  376.          follows:
  377.  
  378.          TitledBox(X1,Y1,X2,Y2,Battr,Tattr,Mattr,style: byte;
  379.                    Title:string);
  380.  
  381.          This method will draw a box from (X1,Y1) to (X2,Y2) using the style
  382.          specified. The box border will be drawn with attribute Battr, the inte-
  383.          rior of the box will be filled using the attribute Mattr, and the title
  384.          string will be drawn in the attribute Tattr.
  385.          By default, the title will be displayed in the center of the top box
  386.          border. However, by embedding some special characters at the beginning
  387.          of the string, you can control precisely where the title is positioned.
  388.          The title can be prefixed with two special character codes to control
  389.          the justification and position of the title.
  390.  
  391.          The justification special characters are as follows:
  392.               '<'   Left Justify
  393.               '>'   Right Justify
  394.               '+'   Center (default)
  395.  
  396.          The position special characters are as follows:
  397.               '^'   Top of box
  398.               '|'   In a drop box
  399.               '_'   Bottom of box
  400.  
  401.          These special characters should be inserted at the beginning of the
  402.          title string. It does not matter in which order the justification and
  403.          position characters are specified. For example, either '<_Hello' or
  404.          '_<Hello' will result in the title 'Hello' being drawn left-justified
  405.          on the bottom box border.
  406.          Listed below is the demo file DEMBX2.PAS, followed by figure 5.3 show-
  407.          ing the resultant output.
  408.  
  409.          Program DemoBoxTwo;
  410.          {DEMBX2}
  411.          USES DOS,CRT, totFAST;
  412.  
  413.          begin
  414.             with Screen do
  415.             begin
  416.                Clear(white,chr(178));
  417.                TitledBox(1,1,19,10,27,31,30,1,'Default');
  418.                TitledBox(21,1,39,10,27,31,30,1,'_Bottom');
  419.                TitledBox(41,1,59,10,27,31,30,1,'|Drop Box');
  420.                TitledBox(61,1,80,10,27,31,30,1,'<Left');
  421.  
  422.  
  423. Writing to the Screen                                                        5-9
  424. --------------------------------------------------------------------------------
  425.  
  426.                TitledBox(1,12,19,22,27,31,30,1,'>Right');
  427.                TitledBox(21,12,39,22,27,31,30,1,'_<Bottom Left');
  428.                TitledBox(41,12,59,22,27,31,30,1,'>|Drop Right');
  429.                TitledBox(61,12,80,22,27,31,30,1,'< Spaced Left ');
  430.                WriteCenter(24,white,'You get the idea!');
  431.                GotoXY(1,25);
  432.             end;
  433.          end.
  434.  
  435.  
  436.  
  437. Figure 5.3                                                              [SCREEN]
  438. Box Title Positions
  439.  
  440.  
  441.  
  442. Drawing Lines
  443.          ScreenOBJ includes the two following methods for drawing simple
  444.          straight lines:
  445.  
  446.  
  447.          HorizLine(X1,X2,Y,Attr,Style:byte);
  448.          This procedure draws a horizontal straight line from (X1,Y) to (X2,Y)
  449.          in the specified attribute. If a style of 1 or 3 is used, a single line
  450.          is drawn. Styles 2 and 4 result in a double line. Any other style
  451.          results in a line being drawn using the ASCII character represented by
  452.          the style number.
  453.  
  454.  
  455.          VertLine(X,Y1,Y2,Attr,Style:byte);
  456.          This method is similar to HorizLine, except that the line is drawn
  457.          vertically from (X,Y1) to (X,Y2).
  458.  
  459.  
  460.  
  461. Intelligent Lines!
  462.          There are two line drawing methods designed to help you draw irregular
  463.          shapes from individual lines. The methods SmartHorizLine and SmartVert-
  464.          Line are similar to HorizLine and VertLine, but smarter! These smart
  465.          methods automatically add joints and corners if the line crosses or
  466.          butts up against another line.
  467.  
  468.          The syntax of the smart line drawing methods is as follows:
  469.  
  470.          SmartHorizLine(X1,X2,Y,Attr,Style:byte);
  471.  
  472.          Draws a horizontal line between (X1,Y) and (X2,Y), using line joining
  473.          characters as necessary.
  474.  
  475.  
  476.  
  477. 5-10                                                                User's Guide
  478. --------------------------------------------------------------------------------
  479.  
  480.          SmartVertLine(X,Y1,Y2,Attr,Style:byte);
  481.  
  482.          Draws a vertical line between (X,Y1) and (X,Y2), using line joining
  483.          characters as necessary.
  484.  
  485.  
  486.          Listed below is the demo program DEMBX3, followed by figure 5.4 illus-
  487.          trating the output.
  488.          Program DemoBoxThree;
  489.          {DEMBX3}
  490.  
  491.          USES DOS,CRT, totFAST;
  492.          begin
  493.             with Screen do
  494.             begin
  495.                TitledBox(1,1,80,25,27,31,30,1,' Smart Line Drawing ');
  496.                FillBox(30,7,50,18,27,2);
  497.                SmartVertLine(10,1,25,27,2);
  498.                SmartVertLine(70,1,25,27,1);
  499.                SmartVertLine(40,7,18,27,2);
  500.                SmartHorizLine(1,80,10,27,1);
  501.                SmartHorizLine(1,80,20,27,2);
  502.                SmartHorizLine(30,50,13,27,1);
  503.                GotoXY(1,25);
  504.             end;
  505.          end.
  506.  
  507.  
  508.  
  509. Figure 5.4                                                              [SCREEN]
  510. Smart Line Drawing
  511.  
  512.  
  513.  
  514. Reading the Screen
  515.          ScreenOBJ includes the following methods to help you read characters
  516.          and attributes directly from the screen:
  517.  
  518.  
  519.          ReadChar(X,Y:byte):char;
  520.          This function method returns the character read from the screen at
  521.          location (X,Y).
  522.  
  523.  
  524.          ReadAttr(X,Y:byte):byte;
  525.          This function method returns the display attribute at the screen loca-
  526.          tion (X,Y).
  527.  
  528.  
  529.  
  530. Writing to the Screen                                                       5-11
  531. --------------------------------------------------------------------------------
  532.  
  533.          ReadWord(X,Y:byte; var Attr:byte; var Ch:char);
  534.  
  535.          This method is a combination of the ReadChar and ReadAttr functions. It
  536.          updates the passed parameters Attr and Ch with the attribute and char-
  537.          acter found at location (X,Y).
  538.  
  539.          ReadStr(X1,X2,Y:byte):string;
  540.  
  541.          The ReadStr method function reads the characters from (X1,Y) to (X2,Y)
  542.          and returns the characters concatenated as a string.
  543.  
  544.  
  545. Drawing Scroll Bars
  546.  
  547.          The totFAST unit includes a global instance pointer ScrollTOT^, which
  548.          defines the cosmetic appearance of all scroll bars used by the Toolkit.
  549.          Refer to page 3-14 for further information on how to change the Scroll-
  550.          TOT^ settings.
  551.          The totWIN unit includes window objects which draw horizontal and ver-
  552.          tical scroll bars. However, the following two ScreenOBJ methods are
  553.          available if you need to draw independent scroll bars. In both methods,
  554.          two values must be passed which control the position of the elevator on
  555.          the slide bar.
  556.  
  557.  
  558.          WriteHScrollBar(X1,X2,Y,Attr:byte; Current,Max:longint);
  559.          This method draws a horizontal scroll bar from (X1,Y) to (X2,Y) in the
  560.          specified attribute. The location of the elevator is controlled by the
  561.          percentage Current is of Max.
  562.  
  563.  
  564.          WriteVScrollBar(X,Y1,Y2,Attr:byte; Current,Max:longint);
  565.          This method draws a vertical scroll bar from (X,Y1) to (X,Y2) in the
  566.          specified attribute. The location of the elevator is controlled by the
  567.          percentage Current is of Max.
  568.  
  569.  
  570.          Listed below is the demo program DEMSC1.PAS which generates the output
  571.          shown in figure 5.5.
  572.  
  573.          Program DemoScrollOne;
  574.          {DEMSC1}
  575.          USES DOS,CRT, totFAST;
  576.  
  577.          begin
  578.             Clrscr;
  579.             with Screen do
  580.             begin
  581.                WriteHScrollBar(1,80,1,31,1,1000);
  582.  
  583. 5-12                                                                User's Guide
  584. --------------------------------------------------------------------------------
  585.  
  586.                WriteHScrollBar(1,80,3,31,950,1000);
  587.                WriteHScrollBar(1,39,5,31,500,1000);
  588.                WriteHScrollBar(41,80,5,31,25,100);
  589.                WriteVScrollBar(1,7,23,31,1,50);
  590.                WriteVScrollBar(3,7,23,31,50,50);
  591.                WriteVScrollBar(5,7,23,31,2,4);
  592.                ScrollTOT^.SetScrollChars(chr(30),chr(31),chr(17),
  593.                                          chr(16),chr(4),chr(219));
  594.                WriteHScrollBar(10,70,11,27,5,10);
  595.                WriteVScrollBar(50,13,23,27,8,10);
  596.                GotoXY(1,24);
  597.             end;
  598.          end.
  599.  
  600.  
  601. Figure 5.5                                                              [SCREEN]
  602. Scroll Bars
  603.  
  604.  
  605.  
  606. Moving Screen Blocks
  607.          ScreenOBJ includes the following three methods to help you manage rect-
  608.          angular areas of the screen:
  609.  
  610.  
  611.          Scroll(Way:tDirection; X1,Y1,X2,Y2:byte);
  612.          The totFAST unit includes the declaration of an enumerated type tDirec-
  613.          tion, which has the members Up, Down, Left, Right, Vert, Horiz. The
  614.          Scroll method can be used to scroll a rectangular portion of the screen
  615.          in any of the first four directions, e.g. Up, Down, Left, or Right. The
  616.          area between the coordinates (X1,Y1) and (X2,Y2) is scrolled in the
  617.          direction specified. One line or column of the display area is removed
  618.          and the opposite line or column is replaced with blanks. For example,
  619.          if the text is scrolled Up, all the text is moved up one line; the
  620.          first line of the area is replaced by the second, and the gap vacated
  621.          by the last line is left blank.
  622.  
  623.  
  624.          CopyScreenBlock(X1,Y1,X2,Y2,X,Y:byte);
  625.          This method takes a rectangular portion of the screen bounded by the
  626.          coordinates (X1,Y1) to (X2,Y2) and copies both the characters and the
  627.          attributes to another location on the screen. The top left coordinates
  628.          of the newly copied block are located at coordinates (X,Y).
  629.  
  630.  
  631.          MoveScreenBlock(X1,Y1,X2,Y2,X,Y:byte);
  632.  
  633.  
  634.  
  635. Writing to the Screen                                                       5-13
  636. --------------------------------------------------------------------------------
  637.  
  638.          This method is similar to CopyScreenBlock, except that the text is
  639.          moved, i.e. it is removed from the original location and repositioned
  640.          so the new top left coordinate is (X,Y).
  641.  
  642. Controlling the Cursor
  643.          The ScreenOBJ object includes a variety of methods for determining the
  644.          cursor location and style, as well as routines to re-position and re-
  645.          size it. Listed below are the public methods related to cursor control.
  646.  
  647.  
  648.          GotoXY(X,Y:byte);
  649.          This method relocates the cursor to the position (X,Y).
  650.  
  651.  
  652.          WhereX:byte;
  653.          This function method returns the X coordinate of the current cursor
  654.          location.
  655.  
  656.  
  657.          WhereY: byte;
  658.          This function method returns the Y coordinate of the current cursor
  659.          location.
  660.  
  661.  
  662.          CursOff;
  663.          This method makes the cursor invisible.
  664.  
  665.  
  666.          CursOn;
  667.          This method makes the cursor visible and sets it to the DOS default
  668.          shape, i.e. a blinking line at the bottom of the character.
  669.  
  670.  
  671.          CursHalf;
  672.          This method makes the cursor a block filling the lower half of the
  673.          character field.
  674.  
  675.  
  676.          CursFull;
  677.          This method makes the cursor a full block filling the entire character
  678.          field.
  679.  
  680.  
  681.          CursReset;
  682.          CursReset moves the cursor to the top left of the display and sets it
  683.          to the DOS default shape.
  684.  
  685. 5-14                                                                User's Guide
  686. --------------------------------------------------------------------------------
  687.  
  688.          CharHeight:integer;
  689.  
  690.          In text mode, an individual character is comprised of a number of scan
  691.          lines. Usually, the cursor is located on one or two scan lines near the
  692.          bottom of the character. Different display systems use varying numbers
  693.          of scan lines. For example, a monochrome display usually has fourteen
  694.          scan lines, as does an EGA system, but a CGA has only eight. This
  695.          method, CharHeight, is a function which returns the actual number of
  696.          scan lines per character. You will need to use this function if you
  697.          want to manually set the cursor shape using CursSize (discussed next).
  698.  
  699.          CursSize(T,B:byte);
  700.  
  701.          This method sets the cursor to the specified top and bottom scan lines.
  702.          The top scan line (e.g. the top bar of the letter "T") is scan line
  703.          zero. As an example, to set the cursor on an EGA system to a half block
  704.          filling the upper half of the character, call CursSize(0,7).
  705.  
  706.          CursTop:byte;
  707.  
  708.          This function method returns the scan line of the uppermost part of the
  709.          cursor.
  710.  
  711.          CursBot: byte;
  712.  
  713.          This function returns the scan line of the lowermost part of the cur-
  714.          sor.
  715.  
  716.          The following program, DEMCU1.PAS, illustrates the main cursor control-
  717.          ling methods. Execute the program to see how the cursor shape changes.
  718.  
  719.          program DemoCursorOne;
  720.          uses DOS,CRT,
  721.               totSYS, totFAST;
  722.  
  723.          var
  724.            Ch : char;
  725.            Temp: byte;
  726.          procedure Msg;
  727.          {}
  728.          begin
  729.             writeln('Character height: ',Screen.CharHeight);
  730.             writeln('Press N-on O-off F-full H-half C-condensed S-25 lines Esc-
  731.          quit');
  732.          end; {Msg}
  733.  
  734.  
  735.  
  736. Writing to the Screen                                                       5-15
  737. --------------------------------------------------------------------------------
  738.  
  739.          begin
  740.             Msg;
  741.             repeat
  742.                Ch := ReadKey;
  743.                case upcase(Ch) of
  744.                'N': Screen.CursOn;
  745.                'O': Screen.CursOff;
  746.                'F': Screen.CursFull;
  747.                'H': Screen.CursHalf;
  748.                'C': begin
  749.                         Temp := Monitor^.SetCondensed;
  750.                         Msg;
  751.                     end;
  752.                'S': begin
  753.                         Monitor^.Set25;
  754.                         Clrscr;
  755.                         Msg;
  756.                     end;
  757.                end; {case}
  758.             until Ch = #027;
  759.             Screen.CursOn;
  760.             Monitor^.Set25;
  761.          end.
  762.  
  763.  
  764.  
  765.  
  766. The Impact of Windows
  767.          You may be familiar with the Turbo Pascal CRT Window command which
  768.          confines writing to a specific area of the screen. The Toolkit also
  769.          supports this basic windowing feature.
  770.  
  771.          Use the method SetWindow to confine screen writing to one area of the
  772.          screen. The method ResetWindow can be used to "remove" the window set-
  773.          tings, i.e. set the window back to the entire display. The method Win-
  774.          dowOFF can be used to temporarily disable the window confinement.
  775.          WindowON is used to reactivate the window settings. Alternatively, the
  776.          method SetWinIgnore will instruct all screen writing operations to
  777.          ignore the current window settings. The full syntax of the window
  778.          related methods are as follows:
  779.  
  780.          SetWindow(X1,Y1,X2,Y2: byte);
  781.  
  782.          Restricts all screen writing to the area within the region (X1,Y1) and
  783.          (X2,Y2). The top left corner of the window area is set to coordinates
  784.          (1,1). Any attempt to write data outside of the window area is ignored,
  785.          and strings which are too long to fit are truncated, i.e. only the
  786.          element of the string which will fit within the window is written.
  787.  
  788.  
  789.  
  790. 5-16                                                                User's Guide
  791. --------------------------------------------------------------------------------
  792.  
  793.          ResetWindow;
  794.  
  795.          Removes the window setting.
  796.  
  797.          WindowActive: boolean;
  798.  
  799.          Returns true if the screen writing is currently restricted within a
  800.          window.
  801.  
  802.          WindowOff: boolean;
  803.  
  804.          Temporarily disables the window settings, and returns true if a window
  805.          was active. This is useful if you want most of the screen writes to be
  806.          confined within a window, but you also want to briefly write some text
  807.          outside the window boundary. For example, the following code fragment
  808.          could be used to write the time at the lower right of the screen:
  809.                   var
  810.                     WinWasActive: boolean;
  811.                   ....
  812.                   WinWasActive := WindowOff;
  813.                   WriteRight(1,25,white,CurrentTime);
  814.                   if WinWasActive then
  815.                      WindowOn;
  816.                   ...
  817.  
  818.  
  819.  
  820.          WindowOn;
  821.          Reactivates the window settings. This method should only be used after
  822.          a call to WindowOff.
  823.  
  824.  
  825.          WindowCoords(var Coords: tByteCoords);
  826.          The totFAST unit includes a type, tByteCoords, which is declared as
  827.          follows:
  828.  
  829.                   tByteCoords = record
  830.                      X1,Y1,X2,Y2: byte;
  831.                   end;
  832.          This method will update the passed parameter Coords with the current
  833.          window settings.
  834.  
  835.  
  836.          SetWinIgnore(On:boolean);
  837.          When passed a True parameter, this method instructs the Toolkit screen
  838.          writing methods to ignore the current window settings, and assume that
  839.          the coordinates (1,1) refer to the top left of the display. Passing a
  840.          False parameter instructs the Toolkit to adjust all screen writes rela-
  841.  
  842.  
  843. Writing to the Screen                                                       5-17
  844. --------------------------------------------------------------------------------
  845.  
  846.          tive to the current method. This method is designed for use in hooked
  847.          procedures when the procedure wants to ignore any window settings which
  848.          may have been effective when it was invoked.
  849.  
  850.  
  851.          Listed below is the demo program DEMFS1.PAS, which illustrates the
  852.          impact of the window commands on screen writing. Figure 5.6 shows the
  853.          screen display generated by the program.
  854.          Program DemoFastOne;
  855.          {DEMFS1}
  856.  
  857.          USES DOS,CRT, totFAST;
  858.          var
  859.            WasOn: boolean;
  860.          begin
  861.             Clrscr;
  862.             with Screen do
  863.             begin
  864.                WriteAt(1,1,white,'* 1,1 (original)');
  865.                WriteAt(5,5,white,'* 5,5 (original)');
  866.                SetWindow(20,8,60,15);
  867.                Clear(31,' ');
  868.                WriteAt(1,1,lightcyan,'* 1,1 (in window)');
  869.                WriteAt(5,5,lightcyan,'* 5,5 (in window)');
  870.                WriteAt(20,7,Lightcyan,'This text is too long to fit!');
  871.                GotoXY(1,2);
  872.                TextColor(Lightcyan);
  873.                System.Writeln('Written with Turbo''s Writeln');
  874.                WasOn := WindowOff;   {disable the window}
  875.                WriteRight(80,23,white,'Written with WindowOff');
  876.                WindowOn;
  877.                WriteAt(1,8,lightcyan,'Window enabled again');
  878.                ResetWindow;
  879.                GotoXY(1,24);
  880.             end;
  881.          end.
  882.  
  883.  
  884.  
  885. Figure 5.6                                                              [SCREEN]
  886. ScreenOBJ Window
  887. Commands
  888.  
  889.  
  890.          Please note that the totWIN unit (discussed in chapter 7) provides
  891.          formatted window support. The window features described in this section
  892.  
  893.  
  894.  
  895. 5-18                                                                User's Guide
  896. --------------------------------------------------------------------------------
  897.  
  898.          simply influence the coordinates of where text is written. The rich
  899.          windows implemented in totWIN save the underlying screen and restore
  900.          the original contents when the window is removed.
  901.  
  902.  
  903.  
  904. Using Virtual Screens
  905.          So far in this chapter, only the physical or visible screen has been
  906.          discussed. Here we see that the totFAST unit also supports virtual
  907.          screens.
  908.  
  909.          A virtual screen can be considered as an invisible screen - you may
  910.          write to the virtual screen, but the changes are not visible on the
  911.          display. A virtual screen can be copied (i.e. displayed) to the visible
  912.          screen at any time.
  913.          Virtual screens allow a programmer to build a number of "out of sight"
  914.          screens which can be popped into view at a moment's notice. A good
  915.          application is the preparation of help screens.
  916.  
  917.          After a virtual screen instance has been initialized with INIT, it must
  918.          be created. A virtual screen can be created by one of two methods. A
  919.          copy can be taken of the physical screen  using the method SAVE, or a
  920.          new blank screen can be created with the method CREATE.
  921.          Once you have created a virtual screen, you can write to it using the
  922.          ScreenOBJ methods as described previously in this chapter. You can also
  923.          set the screen windows and change the cursor location and shape. In
  924.          fact, you can use all the ScreenOBJ methods described in the previous
  925.          section - instead of affecting the visible screen, the virtual screen
  926.          is updated. For example, the following code fragment creates a virtual
  927.          screen, MyScreen, and writes to it:
  928.  
  929.                   with MyScreen do
  930.                   begin
  931.                      Init;
  932.                      Create(80,25,' ');
  933.                      WritePlain(1,1,'This is written to the virtual');
  934.                      WritePlain(1,2,'screen, not the visible screen.');
  935.                      GotoXY(20,20);
  936.                      ....
  937.                   end;
  938.  
  939.  
  940. Saving the Visible Screen
  941.          To create a screen which is a copy of the physical screen, initialize
  942.          the instance and then call the Save method. For example:
  943.  
  944.  
  945.  
  946. Writing to the Screen                                                       5-19
  947. --------------------------------------------------------------------------------
  948.  
  949.                   var Screen1: ScreenOBJ
  950.  
  951.                   begin
  952.                      Screen1.Init;
  953.                      Screen1.Save;
  954.                      ....
  955.                   end.
  956.  
  957.          All the text being displayed on the screen, together with the display
  958.          attributes, is copied to the virtual screen. The virtual screen cursor
  959.          is initially positioned in the same location as the real cursor.
  960.  
  961.  
  962. Creating New Virtual Screens
  963.  
  964.          The Create method is used to create a new virtual screen without copy-
  965.          ing the physical screen. The syntax of the Create method is as follows:
  966.  
  967.          Create(Width,Depth,Attr:byte);
  968.  
  969.          This method creates a virtual screen. The screen will be created Width
  970.          characters wide and Depth lines deep. Any values in the range 1 to 255
  971.          are acceptable. The screen is cleared or blanked, and the display
  972.          attribute is set to Attr.
  973.          The following code fragment shows how to create a virtual screen:
  974.  
  975.                   var Screen1: ScreenOBJ
  976.  
  977.                   begin
  978.                      Screen1.Init;
  979.                      Screen1.Create(100,150,white);
  980.                      ....
  981.                   end.
  982.          Although normally you wouldn't need to call them, there are four func-
  983.          tion methods which return information about the virtual screen. The
  984.          syntax of these methods is as follows:
  985.  
  986.  
  987.          ScreenPtr:pointer;
  988.          Returns a pointer to the heap location of the virtual screen.
  989.  
  990.  
  991.          Width:byte;
  992.          Returns the width of the virtual screen in characters.
  993.  
  994.  
  995.          Depth:byte;
  996.          Returns how many lines deep the virtual screen is.
  997.  
  998.  
  999. 5-20                                                                User's Guide
  1000. --------------------------------------------------------------------------------
  1001.  
  1002.          Exists: boolean;
  1003.  
  1004.          Only returns true when the virtual screen has been created.
  1005.  
  1006.  
  1007. Displaying a Virtual Screen
  1008.  
  1009.          The ScreenOBJ provides a number of methods for displaying all or part
  1010.          of a virtual screen, i.e. transferring the information from the virtual
  1011.          screen to the physical screen. A virtual screen can be instantly dis-
  1012.          played, or slid onto the display with interesting visual effects. Note
  1013.          that the coordinates specified in these methods are global coordinates,
  1014.          i.e. the methods ignore the current window settings.
  1015.          The syntax of the screen displaying methods is as follows:
  1016.  
  1017.  
  1018.          Display;
  1019.          This method instantly transfers the image stored on the virtual screen
  1020.          to the physical screen. If the virtual screen is smaller than the phys-
  1021.          ical screen, the virtual screen will be drawn at the top left of the
  1022.          display. If the virtual screen is larger than the physical screen, the
  1023.          upper-left portion of the virtual screen will be displayed.
  1024.  
  1025.  
  1026.          SlideDisplay(Way:tDirection);
  1027.          This method operates the same as Display, except the virtual screen
  1028.          sl i  d   e    s ... onto the screen -- just for the fun of it! The
  1029.          method is passed a single enumerated type parameter which may have one
  1030.          of the following values:
  1031.  
  1032.          Up         slides up onto the screen from the bottom
  1033.          Down       slides down onto the screen from the top
  1034.  
  1035.          Left       slides left onto the screen from the right
  1036.          Right      slides right onto the screen from the left
  1037.  
  1038.          Vert       slides inwards from the left and the right simultaneously
  1039.                     (like some drapes closing)
  1040.          Horiz      slides inwards from the top and the bottom simultaneously
  1041.                     (like teeth closing)
  1042.  
  1043.  
  1044.          PartDisplay(X1,Y1,X2,Y2,X,Y:byte);
  1045.          This method restores a rectangular portion of the virtual screen from
  1046.          virtual coordinates (X1,Y1) to (X2,Y2) and positions this information
  1047.          with the upper-left corner of the image position at physical coordi-
  1048.          nates (X,Y).
  1049.  
  1050.  
  1051. Writing to the Screen                                                       5-21
  1052. --------------------------------------------------------------------------------
  1053.  
  1054.          PartSlideDisplay(X1,Y1,X2,Y2:byte; Way:tDirection);
  1055.  
  1056.          This method is similar to PartDisplay, except that the image slides
  1057.          onto the display, and the image cannot be relocated, i.e. the image
  1058.          will be placed at coordinates (X1,Y1) on the physical screen.
  1059.  
  1060.  
  1061. Disposing of a Virtual Screen
  1062.  
  1063.          As with all Toolkit objects, the DONE method must be called when the
  1064.          virtual screen instance is no longer required. When Done is called, the
  1065.          memory reserved for the virtual screen is automatically released.
  1066.          Always call Done!
  1067.  
  1068.  
  1069. A Virtual Screen Example
  1070.  
  1071.          Listed below is an abbreviation of the demo program DEMVI1.PAS, which
  1072.          illustrates how to manage virtual screens and create interesting visual
  1073.          effects. We can't show the effects in a manual, so just run the pro-
  1074.          gram!
  1075.          Program DemoVirtualOne;
  1076.  
  1077.          Uses CRT, totFast;
  1078.          Var
  1079.            Screen1,
  1080.            Screen2,
  1081.            Screen3 : ScreenObj;   {screen objects}
  1082.            HeadCol,
  1083.            MsgCol,
  1084.            NormCol : byte;
  1085.  
  1086.          procedure Pause;
  1087.          {}
  1088.          var Ch : char;
  1089.          begin
  1090.             Ch := ReadKey;
  1091.          end; {of proc pause}
  1092.          procedure Initialize;
  1093.          {}
  1094.          begin
  1095.             Screen1.Init;
  1096.             Screen2.Init;
  1097.             Screen3.Init;
  1098.             HeadCol := Attr(yellow,blue);
  1099.             MsgCol  := Attr(yellow,red);
  1100.             NormCol := Attr(white,blue);
  1101.          end; {proc Initialize}
  1102.  
  1103.  
  1104.  
  1105.  
  1106. 5-22                                                                User's Guide
  1107. --------------------------------------------------------------------------------
  1108.  
  1109.          procedure IntroScreen;
  1110.          {}
  1111.          const
  1112.              Tab = 8;
  1113.          begin
  1114.             HeadCol := Attr(yellow,blue);
  1115.             MsgCol  := Attr(yellow,red);
  1116.             NormCol := Attr(white,blue);
  1117.             with Screen do {manipulate the visible screen}
  1118.             begin
  1119.                Clear(NormCol,' ');
  1120.                WriteCenter(1,HeadCol,'TechnoJock''s Object Toolkit');
  1121.                WritePlain(Tab,18,'the display.');
  1122.                WriteRight(80,25,MsgCol,'Press any key to continue ....');
  1123.             end;
  1124.          end; {of proc IntroScreen}
  1125.  
  1126.          procedure BuildScreen2;
  1127.          {}
  1128.          const
  1129.             Tab = 8; Tab1 = 10;
  1130.          begin
  1131.             HeadCol := Attr(yellow,red);
  1132.             MsgCol  := Attr(yellow,red);
  1133.             NormCol := Attr(white,red);
  1134.             with Screen2 do
  1135.             begin
  1136.                Create(80,25,NormCol);
  1137.                WriteCenter(1,HeadCol,'Screen Writing');
  1138.                WritePlain(Tab,6,'methods, including the following:');
  1139.                GotoXY(57,23);
  1140.             end;
  1141.          end; {of proc BuildScreen2}
  1142.          procedure BuildScreen3;
  1143.          {}
  1144.          const
  1145.             Tab = 8;
  1146.          begin
  1147.             HeadCol := Attr(yellow,blue);
  1148.             MsgCol  := Attr(yellow,red);
  1149.             NormCol := Attr(white,blue);
  1150.             with Screen3 do
  1151.             begin
  1152.                Create(80,25,NormCol);
  1153.                TitledBox(1,1,80,25,NormCol,HeadCol,NormCol,4,'|Box drawing');
  1154.                CursOff;
  1155.             end;
  1156.          end; {of proc BuildScreen3}
  1157.  
  1158.  
  1159.  
  1160. Writing to the Screen                                                       5-23
  1161. --------------------------------------------------------------------------------
  1162.  
  1163.          begin
  1164.             Initialize;
  1165.             IntroScreen;
  1166.             BuildScreen2;
  1167.             BuildScreen3;
  1168.             Pause;
  1169.             Screen1.Save;
  1170.             Screen2.SlideDisplay(horiz);
  1171.             Pause;
  1172.             Screen3.SlideDisplay(vert);
  1173.             Pause;
  1174.             with Screen do
  1175.             begin
  1176.                SmartHorizLine(1,80,14,white,1);
  1177.                SmartVertLine(35,8,19,white,2);
  1178.                SmartVertLine(64,10,19,white,2);
  1179.                WriteCenter(25,attr(black,white),'That''s all Folks!');
  1180.             end;
  1181.             Pause;
  1182.             Screen1.Done;
  1183.             Screen2.Done;
  1184.             Screen3.Done;
  1185.             ClrScr;
  1186.             Screen.CursOn;
  1187.          end.
  1188.