home *** CD-ROM | disk | FTP | other *** search
/ Collection of Education / collectionofeducationcarat1997.iso / COMPUSCI / TOT11.ZIP / TOTDOC11.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.