                                   Chapter 8
                                    of the
                            Turbo Pascal Reference

                          The Turbo Vision Reference
                                  (continued)


This chapter is part of the Turbo Pascal Reference electronic freeware book (C)
Copyright 1992 by Ed Mitchell.  This freeware book contains supplementary
material to Borland Pascal Developer's Guide, published by Que Corporation,
1992.  However, Que Corporation has no affiliation with nor responsibility for
the content of this free book.  Please see Chapter 1 of the Turbo Pascal
Reference for important information about your right to distribute and use this
material freely.  If you find this material of use, I would appreciate your
purchase of one my books, such as the Borland Pascal Developer's Guide or
Secrets of the Borland C++ Masters, Sams Books, 1992.  Thank you.

For additional information on using Turbo Vision, including a detailed
tutorial, please see Chapters 11 through 16 of the Borland Pascal Developer's
Guide.


RepeatDelay variable
------------------------------------------------------------ 
Declaration:   RepeatDelay: Word = 8;

Unit:          Drivers

Purpose:
     Determines the number of clock ticks that must occur before generating an
     evMouseAuto event.  evMouseAuto events are automatically generated while
     the mouse button is held down.  A clock tick is 1/18.2 seconds, so the
     default value of 8/18.2 is set at approximately 1/2 second.
     See:  evXXXX constants, DoubleDelay


SaveCtrlBreak variable
------------------------------------------------------------ 
Declaration:   SaveCtrlBreak: Boolean = False;

Unit:          Drivers

Purpose:
     This internal variable is set to the state of the DOS Ctrl-break checking
     at program initialization; at program termination, DOS's Ctrl-break
     trapping is restored to the value saved in SaveCtrlBreak.
     See:  InitSysError, DoneSysError


sbXXXX constants
------------------------------------------------------------ 
Scrollbar constants

Constant        Value Usage
sbLeftArrow     0     The horizontal scroll bar's left arrow.
sbRightArrow    1     Horizontal scroll bar's right arrow.
sbPageLeft      2     The page area to the left of the position
                      indicator.
sbPageRight     3     The page indicator to the right of the
                      indicator.
sbUpArrow       4     Vertical scroll bar's up arrow.
sbDownArrow     5     Vertical scroll bar's down arrow.
sbPageUp        6     Paging area above the position indicator.
sbPageDown      7     Paging area below the position indicator.
sbIndicator     8     Position indicator on the scroll bar.
sbHorizontal    $0000 The scroll bar is horizontal.
sbVertical      $0001 The scroll bar is vertical.
sbHandleKeyboard      $0002   Scroll bar accepts keyboard commands.

Use one of the first 9 sbXXXX constants as a parameter to
TScrollBar.ScrollStep.  The last 3 sbXXXX constants, sbHorizontal, sbVertical,
sbHandleKeyboard are used to specify a horizontal, vertical, or keyboard
accessable scrollbar when a scroll bar is created using the
TWindow.StandardScrollBar function.

See:  TScrollBar.ScrollStep, TScrollBar, TWindow.StandardScrollBar


ScreenBuffer variable
------------------------------------------------------------ 
Declaration:          ScreenBuffer: Pointer;

Unit:                 Drivers

Purpose:
     This internal pointer is initialized by InitVideo and keeps track of the
     location of the video screen buffer.


ScreenHeight variable
------------------------------------------------------------ 
Declaration:          ScreenHeight : Byte;

Unit:                 Drivers

Purpose:
     Holds the current height of the screen, in lines.  For example, 25, 43 or
     50 would be typical values.
     See:  SetVideoMode


ScreenMode variable
------------------------------------------------------------ 
Declaration:          ScreenMode : Word;

Unit:                 Drivers

Purpose:
     Contains the current video mode as determined by the smXXXX constants
     passed to the SetVideoMode procedure.
     See:  SetVideoMode, smXXXX constants


ScreenWidth variable
------------------------------------------------------------
Declaration:          ScreenWidth : Byte;

Unit:                 Drivers
     Holds the current width of the screen in number of characters per line
     (for example, 80).

 
SetMemTop procedure
------------------------------------------------------------
Declaration:  
     procedure SetMemTop(MemTop : Pointer);

Unit:  Memory

Purpose:
     SetMemTop sets the top of the memory block allocated to an application. 
     Initially, MemTop is set to the top of the heap, stored in HeapEnd.  By
     resetting the top of memory to the HeapPtr, all the remaining free memory
     is available for other uses.  This is especially useful when shelling out
     to another application, as shown in this example code from TVSHELL8.PAS
     (see Chapters 11-12 in Borland Pascal Developer's Guide):

procedure TShell.RunProgram ( ProgName, ParamStr : String );
     { Launches the program in 'ProgName' with the command line
       parameters in 'ParamStr' }
begin
  ClrScr;
  DoneSysError;
  DoneEvents;
  DoneVideo;
  DoneMemory;
  SetMemTop(HeapPtr);
  SwapVectors;
  Exec( ProgName, ParamStr );
  SwapVectors;
  SetMemTop(HeapEnd);
  InitMemory;
  InitVideo;
  InitEvents;
  InitSysError;
  Shell.ReDraw;
end; { RunProgram }


SelectMode type
------------------------------------------------------------ 
Declaration:       
     SelectMode = (NormalSelect, EnterSelect, LeaveSelect);

Unit:     Views

Purpose:
     An internal value used by Turbo Vision.


SetVideoMode procedure
------------------------------------------------------------ 
Declaration:
     procedure SetVideoMode( Mode: Word );

Unit:              Drivers

Purpose:
     Use this (or more commonly TProgram.SetScreenMode) to select 25 or 43/50
line screen height, in conjunction with selecting the color, black & white or
monochrome palettes.  To change to the  color palette, write,
     SetVideoMode( smCO80 );
where smCO80 is one of the smXXXX screen mode constants.  Optionally, to select
43/50 line mode, add the smFont8x8 constant to the color selection constant. 
For example,
     SetVideoMode( smMono + smFont8x8 );
Normally, you should use TProgram.SetScreenMode, which has the same parameter
value, to change the screen color or screen size.  SetScreenMode properly
handles resetting of the application palettes, repositioning the mouse pointer
and so on.

See:  TProgram.SetScreenMode, smXXXX constants


sfXXXX constants
------------------------------------------------------------ 
State Flag constants

     Use TView.SetState to set the state bits, from the table below, into a
TView's State field.  Example usage:
     SetState( sfCursorIns, True );
where the first parameter is the state value to change, and the second
parameter is True to enable the selected condition, or False to disable the
selected condition.  Some of the bits are not normally set by the programmer
but rather by methods in Turbo Vision.  You can, however, read and test the
values in TView.State directly.

Constant  Value    Usage
sfVisible $0001
                    Set when the view is visible in front of its owner (for
                    example, a button on a dialog) but note that a visible
                    view's owner may itself be hidden from view.  Call
                    TView.Exposed to determine if a view is actually visible on
                    the screen, and use TView.Hide to clear this bit and hide
                    the view, and TView.Show to set this bit and make the view
                    visible.

sfCursorVis        $0002
                    Set when the view's cursor is visible.  Use
                    TView.ShowCursor to make the cursor visible and set this
                    bit, or TView.HideCursor to hide the cursor and clear this
                    bit.

sfCursorIns        $0004
                    Set when the cursor is a solid block (the "insert" cursor),
                    clear when the cursor is an underscore (the "overstrike"
                    cursor).  Call TView.BlockCursor to set this bit, and
                    TView.NormalCursor to clear the bit.

sfShadow  $0008
                    Set when the view has a shadow.

sfActive  $0010
                    Set whenever the view is an active window or a subview
                    within an active window.  For example, when using the IDE
                    to edit multiple files, only the editor that you are
                    currently using is the active window.

sfSelected         $0020
                    Set when this view is selected.  (See TView.Selected).

sfFocused $0040
                    If the view is part of the focus chain (see Chapter 13,
                    "More Turbo Vision Features" in the Borland Pascal
                    Developer's Guide), then this bit is set.

sfDragging         $0080
                    Set whenever the view is being dragged.

sfDisabled         $0100
                    Set if the view has been disabled and is no longer
                    processing events.

sfModal   $0200
                    Whenever a view is displayed using the ExecView call, that
                    view becomes a modal view (as compared to a view that has
                    been inserted into the desktop).  This bit is set when the
                    view is the modal view and controls how events are sent
                    through the view hierarchy.

sfExposed $0800
                    Set when a view is possibly visible on the screen.  Don't
                    check this flag directly because a visible view can still
                    be hidden due to clipping.  Instead, call TView.Exposed to
                    determine if the view is actually visible.

See:  TView.BlockCursor,  TView.Exposed, TView.Hide, TView.HideCursor,
TView.NormalCursor, TView.SetState, TView.Show, TView.ShowCursor, 


ShadowAttr variable
------------------------------------------------------------ 
Declaration:
     ShadowAttr: Byte = $08;

Unit:              Views
Purpose:
     The ShadowAttr byte contains the video attribute for the color of the
     shadow display on some views and windows.  See Chapter 13, "More Turbo
     Vision Features" in the Borland Pascal Developer's Guide for details on
     selecting different colors for video attribute bytes
     See:  ShadowSize


ShadowSize variable
------------------------------------------------------------ 
Declaration:
     ShadowSize: TPoint = (X: 2; Y: 1);

Unit:              Views
Purpose:
     ShadowSize determines the size of the shadow area on those views that
     contain a shadow.  The default value is 2 characters wide and 1 character
     high.
     See: ShadowAttr


ShowMarkers variable
------------------------------------------------------------ 
Declaration:
     ShowMarkers: Boolean;

Unit:              Drivers

Purpose:
     When using color displays, Turbo Vision uses different colors to highlight
the default button selections, the location of the list box cursor and so on. 
When using the monochrome color palette, Turbo Vision adds small marker
characters to various controls to make them easier to identify and when
necessary to highlight a default selection.  For example, default buttons have
small right and left arrows to highlight the default button:

     -> [ Okay ] <-     [Cancel]

When the monochrome color palette is selected, ShowMarkers is set to True and
is normally set False for the other color palettes.  If you wish, you can set
ShowMarkers True for both CColor and CBlackWhite palettes.


ShowMouse procedure
------------------------------------------------------------ 
Declaration:
     procedure ShowMouse

Unit:              Drivers

Purpose:
     ShowMouse is the opposite of the HideMouse.  Call HideMouse to hide the
     mouse cursor and simultaneously increment a "mouse hidden counter". 
     ShowMouse decrements the counter, and when it reaches zero, makes the
     mouse cursor visible again on the screen.
     See: HideMouse


smXXXX constants
------------------------------------------------------------ 
Screen Mode Constants

Use the constants from the table below when selecting Black & White, Color or
Monochrome color palettes, or switching between 25 and 43- or 50 line display
modes.  Use of these constants is described in "The Set Up Program Dialog" in
Chapter 12, and also in Chapter 13 of the Borland Pascal Developer's Guide.

Constant  Value    Usage
smBW80    $0002    Black and white/gray scale
smCO80    $0003    Color mode
smMono    $0004    Monochrome mode
smFont8x8 $0100    43 or 50 line modes

See: SetVideoMode, ScreenMode, TProgram.SetScreenMode


SpecialChars variable
------------------------------------------------------------ 
Declaration:
     SpecialChars: array [0..5] of Char =
          (#175, #174, #26, #27, ' ', ' ')

Unit:              Views

Purpose:
     These constants define the special marker characters used when the
     ShowMarkers variable is set to True.
     See: ShowMarkers


stXXXX constants
------------------------------------------------------------
Stream constants

These constants are used when opening a stream file, to specify the access
mode, and by the streams system to return error condition codes.  For
additional information, see Chapter 21, Streams.

Stream access modes passed to the TStream.Init constructor
Constant    Value  Usage
stCreate    $3C00  Create and open the file
stOpenRead  $3D00  Open an existing file as a read-only file
stOpenWrite $3D01  Open an existing file as write-only.
stOpen      $3D02  Open an existing file with read/write access

Stream error codes set in TStream.Status
Constant    Value  Usage
stOk         0     No error
stError     -1     Access error occurred
stInitError -2     Unable to initialize the stream
stReadError -3     An attempt was made to read past the end of
                   the file
stWriteError       -4            For some reason (perhaps out of disk space)
                   the stream could not be expanded.
stGetError  -5     An unregistered object type was found in the
                   file by the Get method.
stPutError  -6     Put tried to write an unregistered object
                   type to the stream


StartupMode variable
------------------------------------------------------------ 
Declaration:       
     StartupMode : Word;

Unit:              Drivers

Purpose:
     This internal variable stores the existing screen mode before Turbo Vision
     switches to a new screen mode.
     See:  DoneVideo, ScreenMode 


StatusLine variable
------------------------------------------------------------ 
Declaration:       
     StatusLine: PStatusLine = nil;

Unit:              App

Purpose:
     StatusLine is initialized by the call to TProgram.InitStatusLine.   See
     Chapter 14, Turbo Vision Tutorial for a detailed description of
     initialization a program's status line.


StreamError variable
------------------------------------------------------------ 
Declaration:       
     StreamError: Pointer = nil;

Unit:              Objects

Purpose:
     To override all stream error handling, set StreamError to point to a far
procedure that you have defined.  Thereafter, whenever any error occurs, on any
stream that is in use, your procedure will receive control.  This enables you
to write a single procedure to intercept and process all stream error
conditions.  Alternately, you can override TStream.Error to intercept error
conditions for individual streams.
     Example usage:
     procedure HandleStreamErr( var S : TStream); far;
     ...
     StreamError := @HandleStreamErr;


SysColorAttr variable
------------------------------------------------------------ 
Declaration:       
     SysColorAttr: Word = $4E4F;

Unit:              Drivers

Purpose:
     On color displays, SysColorAttr specifies the attribute bytes for system
     error messages.  (SysMonoAttr specifies the attribute bytes for monochrome
     ). System error messages are DOS crtical errors (such as floppy disk drive
     not accessible) and other device type errors.  System errors are displayed
     on the status line in the color specified by the second part of 
     SysColorAttr, $4F, white on red text.  The first part, $4E, is used for
     highlighting command keys, such as Enter or Esc.
     See:   SystemError, SysMonoAttr, Chapter 13, "More Turbo Vision Features".


SysErrActive variable
------------------------------------------------------------ 
Declaration:       
     SysErrActive : Boolean = False;

Unit:              Drivers

Purpose:
            If True, then the system error handler is available for use.


SysErrorFunc variable
------------------------------------------------------------ 
Declaration:       
     SysErrorFunc : TSysErrorFunc = SystemError;

Unit:              Drivers

Purpose:
     SysErrorFunc points to the system error handling procedure.  You can
override system error handling by writing your own procedure and assigning it
to the SysErrorFunc variable.  The default system error handler is defined as,

     function SystemError
            (ErrorCode: Integer; Drive: Byte): Integer;

where ErrorCode is a value from the table below, and Drive is the drive number
(A=1, B=1, C=3, and so on).  SystemError should return 0 if the user requests
to retry the operation or 1 if the user elected to abort the function.

Table of System Error Codes
Error code  Usage
0           Disk is write protected
1           Critical disk error
2           Disk is not ready
3           Critical disk error
4           Data integrity error
5           Critical disk error
6           Seek error
7           Unknown media type
8           Sector not found
9           Printer out of paper
10          Write fault
11          Read fault
12          Hardware failure       
13          Bad memory image of file allocation table
14          Device access error
15          Drive swap notification (floppy disks have changed)

See:  SysColorAttr, SysErrActive, SysErrorFunc, SysMonoAttr, SystemError,
TSysErrorFunc, InitSysError


SysMonoAttr variable
------------------------------------------------------------ 
Declaration:       
     SysMonoAttr: Word = $7070;

Unit:              Drivers

Purpose:
     On monochrome displays, SysMonoAttr specifies the attribute bytes for
     system error messages.  (SysColorAttr specifies the attribute bytes for
     color). System error messages are DOS crtical errors (such as floppy disk
     drive not accessible) and other device type errors.  See SysColorAttr for
     more information about the attribute values.
     See:   SystemError, SysColorAttr, Chapter 13, "More Turbo Vision Features"
     in Borland Pascal Developer's Guide.


SystemError function
------------------------------------------------------------ 
Declaration:       function SystemError( ErrorCode: Integer;  Drive:Byte):
Integer;

Unit:              Drivers

Purpose:
     This function handles system errors (such as DOS critical errors).  See
     SysErrorFunc for details on the parameters and their values.  SystemError
     returns 0 if the user requests that the operation be retried, and 1 if the
     user elects to cancel the operation.
     See:  SysErrorFunc          


TApplication object
------------------------------------------------------------ 
Turbo Vision Hierarchy
  TObject
     TView
       TGroup
          TProgram
            TApplication

Discussion
     The TApplication object is the generic application from which most of the
     Turbo Vision programs you write will be derived.  For examples, see the
     TVSHELL  sample programs of Chapters 11-12 in the Borland Pascal
     Developer's Guide.  As shown in Listing 11.1 (of the Developer's Guide),
     TShell is defined as an instance of TApplicatio.  TApplication is nearly
     identical to TProgram; the only difference is in the Init and Done
     destructors.  

Commonly Used Features
     Generally, the only methods used are TApplication.Init, TApplication.Done,
     and TApplication.Run, which is inherited from TProgram.Run.  See also
     TProgram for other methods that are available to TApplication objects.

Example
type
  TShell = object(TApplication)
    DirWindow : PDirectoryWindow;

    procedure InitMenuBar; virtual;
    procedure InitStatusLine; virtual;
    constructor Init;
  end; { TShell }

var
  Shell     : TShell;       { Create an instance of the TShell object }


procedure TShell.InitMenuBar;
{ Purpose:
  Defines the pulldown menus used in Shell
}
var
  Bounds: TRect;

begin

  TShell.GetExtent(Bounds);
  Bounds.B.Y := Bounds.A.Y + 1;
  MenuBar := New(PMenuBar, Init(Bounds, NewMenu(
    NewSubMenu('~R~un', hcNoContext, NewMenu(
      NewItem('~R~un', '', 0, cmRunProgram, hcNoContext,
  ...
end;


procedure TShell.InitStatusLine;

{ Purpose:
  Defines the Status Line shown on the bottom line of the screen
  within TShell
}
var
  Bounds: TRect;

begin
  GetExtent(Bounds);
  Bounds.A.Y := Bounds.B.Y - 1;
  StatusLine := New(PStatusLine, Init(Bounds,
    NewStatusDef(0, $FFFF,
      NewStatusKey('', kbF10, cmMenu,
      NewStatusKey('~Alt-X~ Exit', kbAltX, cmQuit,
      NewStatusKey('~F2~ Copy', kbF2, cmCopy,
      NewStatusKey('~F3~ Close', kbF3, cmClose,
      nil)))),
    nil)
  ));
end; { TShell.InitStatusLine }


constructor TShell.Init;

var
  Bounds : TRect;

begin
  TApplication.Init;
end; { TShell.Init }


begin

  Shell.Init;
  Shell.Run;
  Shell.Done;

end.


Fields
     none

Methods

destructor  Done; virtual;
     Calls TProgram.Done, DoneHistory, DoneSysError, DoneEvents, DoneVideo, and
     DoneMemory.

constructor Init;
       Calls InitMemory, InitVideo, InitEvents, InitSysError, InitHistory and
     TProgram.Init.



TBackground object
------------------------------------------------------------ 
Turbo Vision Hierarchy
  TObject
     TView
       TBackground

Discussion
     TBackground contains the background pattern that forms the backdrop of
     most Turbo Vision applications.  TBackground is automatically initialized
     by the TDeskTop object that owns all of the application views.  

Commonly Used Features
       Normally, you will have no need to directly use the TBackground object. 
     However, if you wish to create a different background object, you will
     need to override TProgram.InitDeskTop, to instantiate a new TDeskTop with
     an overridden TDeskTop.NewBackground function.  NewBackground, in turn,
     creates the new TBackground object by calling TBackground.Init to specify
     a new background pattern.

Example:
   1  { DEMOTBAC.PAS }
   2  program DemoTBackground;
   3  
   4  uses
   5    Objects, App, Views;
   6  
   7  type
   8    TSampleProgram = object(TApplication)
   9      procedure InitDeskTop; virtual;
  10    end;
  11  
  12    PNewDeskTop = ^TNewDeskTop;
  13    TNewDeskTop = object(TDeskTop)
  14      procedure InitBackground; virtual;
  15    end;
  16  
  17  var
  18    SampleProgram : TSampleProgram;
  19  
  20  
  21  procedure TNewDeskTop.InitBackground;
  22  Var
  23    Bounds: TRect;
  24    Temp : PBackground;
  25  begin
  26    { Program never gets here ???? }
  27    Bounds.Assign( 0, 1, 80, 24 );
  28    Temp := New( PBackground, Init( Bounds, Char($FF) ) );
  29    Insert(Temp);
  30    Background := Temp;
  31  end;
  32  
  33  
  34  procedure TSampleProgram.InitDeskTop;
  35  Var
  36    Bounds: TRect;
  37  begin
  38    Bounds.Assign( 1, 0, 80, 24 );
  39    DeskTop := New( PNewDeskTop, Init( Bounds ) );
  40  end;
  41  
  42  
  43  begin
  44    with  SampleProgram  do
  45    begin
  46      Init;
  47      Run;
  48      Done;
  49    end;
  50  end.
  51  


Fields
Pattern: Char;
       Contains the bit pattern describing the background's appearance.  This
     value is initialized by TDeskTop.InitBackground calling TBackground.Init.

Methods
procedure Draw; virtual;
       Using the palette returned by GetPalette, draws the background using the
     specified Pattern.  You can override this method to create a new type of
     background, say perhaps one containing text or boxes or what ever you
     desire.  To do that, derive a new TDeskTop object and a new TBackground
     object, using the method outline in the sample Listing above, and override
     TBackground.Draw to display the background in the format that your
     require.

function GetPalette: PPalette; virtual;
       Returns a pointer to the CBackground color palette.  To change the color
     scheme, you need to override this method (see TBackground.Draw, above).

constructor Init(var Bounds: TRect; APattern: Char);
       Call TBackground.Init via TDeskTop.InitBackground, to create a new
     background object of the size specified by Bounds, and having the
     replicated bit pattern indicated by APattern. See: 
     TDeskTop.InitBackground

constructor Load(var S: TStream);
       Creates a new TBackground object and reads its attributes from stream S
     by calling TView.Load, and then S.Read(Pattern).

procedure Store(var S :TStream);
     Writes the TBackground object to stream S, by calling TView.Store, and
     then S.Write(Pattern).


TBufStream object
------------------------------------------------------------ 
Turbo Vision Hierarchy
  TObject
     TStream
       TDosStream
          TBufStream

Discussion
     The TBufStream object type is a derivative of TStream and TDosStream and
     is probably the type you will most often use for writing and reading 
     streams to and from disk files.  TBufStream implements a buffered version
     of TDosStream, which greatly improves the speed and efficiency of stream
     I/O, particularly when writing or reading a lot of small objects.   See
     Chapter 15, "Streams" in the Borland Pascal Developer's Guide for a
     tutorial on the use of stream I/O.
     See:  TDosStream, TStream, stXXXX constants

Commonly Used Features
     Generally, you will use the TBufStream.Init method to open a stream file
     for access, the TBufStream.Read and TBufStream.Write methods for
     performing input and output, and TBufStream.Done to close and dispose of
     the object.  For random access streams, you will use TBufStream.Seek to
     position the file pointer to the proper object reocrd.  You may also wish
     to use TBufStream.Flush or TBufStream.Truncate, as appropriate.

Example
   1  { DEMOTBUF.PAS }
   2  var
   3    PhoneBook : PCollection;
   4    PhoneBookFile : TBufStream;
   5  
   6  ...
   7  
   8  
   9  { TPersonInfo is a collection object holding name and
     address information }
  10  procedure TPersonInfo.Store ( var S : TStream );
  11  begin
  12  
  13    S.Write( Name, SizeOf( Name ));
  14    S.Write( Address, SizeOf( Address ));
  15    S.Write( City, SizeOf( City ));
  16    S.Write( State, SizeOf( State ));
  17    S.Write( Zip, SizeOf( Zip ));
  18    S.Write( Age, SizeOf( Age ));
  19  
  20  end;
  21  
  22  
  23  constructor TPersonInfo.Load ( var S : TStream );
  24  begin
  25  
  26    S.Read( Name, SizeOf( Name ));
  27    S.Read( Address, SizeOf( Address ));
  28    S.Read( City, SizeOf( City ));
  29    S.Read( State, SizeOf( State ));
  30    S.Read( Zip, SizeOf( Zip ));
  31    S.Read( Age, SizeOf( Age ));
  32  
  33  end;
  34  
  35  ...
  36  
  37    { Register the PersonInfo object type }
  38    RegisterType( RPersonInfo );
  39  
  40    { Open the stream file }
  41    PhoneBookFile.Init('FONEBOOK.DAT', stCreate, 1024 );
  42  
  43    { Tell the PhoneBook collection to put itself to the stream }
  44    PhoneBookFile.Put( PhoneBook );
  45  
  46    { Close the file }
  47    PhoneBookFile.Done;

Fields
BufEnd: Word; { Read only }
     BufEnd is an index to the last used byte in Buffer.

Buffer: Pointer; { Read only }
     Points to the beginning of the stream's buffer.

BufPtr: Word; { Read only }
     Points to the current location in Buffer.

BufSize: Word; { Read only }
     Contains the size of the buffer, in bytes.


Methods
destructor Done; virtual;
     Flushes the buffer to disk, closes the file and disposes of the stream
     object.

procedure Flush; virtual;
Override:  Never
     Forces the buffer contents to be written out to disk.

function GetPos: Longnt; virtual;
Override:  Never
     Gives the stream's current position relative to the start of the sream. 
     Important:  This is not the same as BufPtr which is the current position
     relative to the start of the current buffer only.  GetPos corresponds to
     the action of Seek, below, which positions the stream's current location
     to a byte location in the stream file.

function GetSize: Longint; virtual;
Override:  Never
     Writes the contents of the buffer out to disk (via Flush) and returns the
     total number of bytes in the stream.

constructor Init( Filename: FNameStr; Mode, Size : Word);
     Use Init to create and initialize a stream, using the parameters Filename
     to contain the name of the file open, setting the Mode parameter to
     stCreate, stOpenRead, stOpenWrite or stOpen, and Size to the number of
     bytes to allocate for a buffer area.

procedure Read( var Buf; Count: Word); virtual;
Override:  Never
     Use Read to read Count bytes from the stream and into the Buf parameter. 
     Read begins at the stream's current position (as determined by Seek or
     beginning at the end of the previous Read operation).
     See:  Chapter 15, "Streams" in the Borland Pascal Developer's Guide, Seek,
     Write

procedure Seek(Pos : Longint); virtual;
Override:  Never
     Empties the contents of the Buffer to disk and then positions the current
     stream position to Pos.  You can use Seek to implement random access to
     stream files (see Chapter 15, "Streams").  Be certain that if you are
     adding or multiplying values to compute the Pos parameter (for example,
     SizeOf(SomeObject) * Index), that you convert the parameters to Longint to
     avoid integer overflow errors.
     See:  Chapter 15, "Streams" in the Borland Pascal Developer's Guide,
     GetPos, Read, Write

procedure Truncate; virtual;
     Use Truncate to flush out the Buffer, and delete all data following the
     current position in the stream.

procedure Write( var Buf; Count: Word); virtual;
     Use Write to copy Count bytes from the Buf parameter to the stream. 
     See:  Chapter 15, "Streams" in the Borland Pascal Developer's Guide, Read


TButton object
------------------------------------------------------------ 
Turbo Vision Hierarchy
  TObject
     TView
       TButton

Discussion
     Use the TButton object to place button controls into dialog boxes.  Each
     time that a button is "pressed" by clicking on it with the mouse, or using
     a keyboard shortcut key or tabbing to the button and pressing SpaceBar or
     Enter, the button generates a cmXXXX command.

Commonly Used Features
     Generally, you need only Init a TButton object and insert it in to the
     owning TGroup, which is typically a TDialog.  You rarely need to override
     any of its methods or reference its fields.

Example
  with  Dialog^  do
  begin
     { Create the Okay and Cancel buttons }
     Bounds.Assign (7, 10, 16, 12 );
     Insert( New( PButton, Init( Bounds, '~O~kay', cmOk,
          bfDefault )));
     Bounds.Assign ( 24, 10, 33, 12 );
     Insert( New( PButton, Init( Bounds, '~C~ancel', cmCancel,
          bfNormal )));
     ...
  end; { with Dialog }
  Control := DeskTop^.ExecView( Dialog );

Fields
AmDefault: Boolean; { Read only }
     When True, this button is the default button, and when False, this is a
     normal button.

Command : Word; { Read only }
     Holds the command code value that is generated when the button is pressed.

Flags : Byte; { Read only }
     The flags byte is a bit mapped field indicating if the label text is left
     justified or center, and if the button is the default button in the group,
     or is a normal, non-default button. See:  bfXXXX constants

Title : PString; { Read only }
     Points the string containing the button's label text.


Methods

destructor Done; virtual;
     Disposes the memory allocated to Title and calls TView.Done.

procedure Draw; virtual;
Override:  If needed.
     Draws the button using the palette returned by GetPalette, and by
     referencing the Flags, AmDefault and TView.State fields to display the
     button as a normal button, default button or disabled button, with left
     justified or centered title.

function GetPalette: PPalette; virtual;
Override:  If needed.
     Returns a pointer to the CButton color palette, but can be overridden to
     provide other color choices.  CButton entries are intended to map into the
     CDialog palette.  If, for some reason the TButton is not inserted into a
     TDialog group, you will almost certainly have to override this function.

procedure HandleEvent(var Event: TEvent); virtual;
Override: If needed.
     Processes events received by the button.  These include mouse clicks,
     keyboard short cut keys, Enter, SpaceBar, and several internal commands
     used to process evBroadcast messages notifying buttons when the default
     button changes.

constructor Init(var Bounds: TRect; ATitle: TTitleStr; ACommand: Word;  AFlags:
Byte);
     Init is the only method that you are likely to use for the TButton object.
     Use Init to create a button with a size and location specified in Bounds,
     and a button label specified by ATtitle.  Pass the cmXXXX command constant
     to ACommand, to be returned if the button is pressed.  For the AFlags
     parameter, you can pass one of the bfXXXX constants to initialize this
     button as the bfDefault or bfNormal button, and can optionally or one of
     the contstants with bfLeftJustify left justify the button label instead of
     using the centering default. 

constructor Load(var S: TStream);
     Creates a new instance of a TButton object and reads its definition from
     stream S.  Use the TButton.Load method, in conjunction with Store, for
     reading dialog boxes directly from resource files.  This topic is covered
     in detail in chapter 16, "Resources" in the Borland Pascal Developer's
     Guide.
     See:  TButton.Store

procedure MakeDefault(Enable : Boolean);
     Call a button's MakeDefault method to force the button to become the
     default button, by setting Enable to True.  If Enable is False, the
     default status of this button is removed.   Normally, this is handled
     internally to the TDialog object that owns the button.

procedure SetState( AState: Word; Enable: Boolean); virtual;
     If needed, call this method to change the TView.State field inherited from
     TView.  If the button becomes sfSelected or sfActive, SetState
     automatically handles making the button the default or non-default, as
     needed.

procedure Store( var S : TStream);
     Writes this button object out to stream S.  Use in conjunction with Load
     for the creation and reading of resource files.  See:  TButton.Load


TByteArray type
------------------------------------------------------------ 
Declaration:       TByteArray = array[0..32767] of Byte;
Unit:       Objects
Purpose:
  TByteArray is generic array of bytes useful for typecasting.


TCheckBoxes object
------------------------------------------------------------ 
Turbo Vision Hierarchy
  TObject
     TView
       TCluster
          TRadioButtons
          TCheckBoxes
          
Discussion
     Use TCheckBoxes to implement groups of check box controls in dialogs. 
     Eachgroup can have up to 16 check boxes, any number of which may be
     "checked" at the same time.  See Chapter 11, "Turbo Vision Tutorial" in
     the Borland Pascal Developer's Guide contains a tutorial on the creation
     and use of the TCheckBoxes object.

Commonly Used Features
     Normally, you create groups of checkboxes using the inherited Init method.
     Rarely will you have a need to use or override the other methods.
     See:  TCluster, TRadioButtons

Fields
     None

Methods
procedure Draw; virtual;
     Draws the checkboxes by calling TCluster.DrawBox and sets each checkbox
     indicator to "[  ]" if the item is not checked, and to "[ X ]" if the item
     is checked.  See TCluster.DrawBox for instructions on using that method to
     draw the indicators.  You only need to override this method if you plan to
     use a different type of indicator for checkboxes.

function Mark( Item: Integer ) : Boolean; virtual;
     The items in the check box cluster are numbered from 0 up to a maximum of
     15 items.  By passing the item number corresponding to a specific check
     box, you can test to see if the Item'th check box has been set to 
     "[ X ]".
     See:  TCheckBox.Press

procedure Press( Item : Integer ); virtual;
     Press sets or clears a check box item.  Like Mark, the parameter Item
     specifies which of the check boxes, from 0 up to a maximum of 15 to set or
     clear.  Press toggles the check box:  if the checked box is already
     checked, then Press clears it and vice versa.
     See:  TCheckBox.Mark


TCluster object
------------------------------------------------------------ 
Turbo Vision Hierarchy
  TObject
     TView
       TCluster
          TRadioButtons
          TCheckBoxes

Discussion
     The TCluster objects are used to creat groups of dialog box controls.  
     Both TRadioButtons and TCheckBoxes inherit almost all of their
     functionality from TCluster due to their strong similarities.  

Commonly Used Features
     Generally, you will use either TRadioButtons or TCheckBoxes and directly
     insert those controls into dialogs.  While TCluster provides several
     fields and methods, these are primarily of interest if you are building a
     new cluster-type control.

Fields

Sel: Integer; { Read only }
     Sel indicates which of the buttons or check boxes is currently the active
     one.

Strings : TStringCollection; { Read only }
     Strings is a collection containing the text of all the items in the
     control group.

Value: Word; { Read only }
     Value holds the current setting of the control.  For TCheckBoxes, Value is
     a bit pattern where each bit indicates the state of a checked box, and for
     TRadioButtons, Value is the item number of the button that is pressed.

Methods
destructor Done; virtual;
     Disposes of the Strings collection and calls TView.Done.

function DataSize: Word; virtual;
     This function is used in conjunction with GetData and SetData, to obtain
     the SizeOf(Value).

procedure DrawBox(Icon: String; Marker: Char);
     DrawBox draws the status indicator for each check box or icon and is
     called by TCheckBoxes.Draw or TRadioButtons.Draw.  The Icon parameter
     holds '[  ]' for check boxes, or '( )' for radiobuttons.  Marker contains
     the character to indicate the item is selected (for example, 'x' for
     checkboxes). 

procedure GetData(var Rec); virtual;
     Used to copy the Value field to Rec when retrieving dialog data.

function GetHelpCtx: Word; virtual;
     Returns HelpCtx + Sel, where Sel is the current active item in the
     cluster.  Using this method you can produce context sensitive help for
     individual items in each cluster.

function GetPalette: PPalette; virtual;
     Returns a pointer to CCluster color palette.  Override this method to
     implement a different color sheme for cluster items.

procedure HandleEvent(var Event: TEvent); virtual;
     Handles selection of cluster items through the keyboard movement keys and
     SpaceBar (to toggle a selection).  Other events are passed through to
     TView.HandleEvent.

constructor Init( var Bounds: TRect; AStrings: PSItem);
     Use Init and nested calls to NewSItem to create an entire list of cluster
     items within the area described by Bounds.  Normally, TCluster.Init is
     called via the derived objects TRadioButtons.Init or TCheckBoxes.Init, as
     shown in this example:

     Bounds.Assign( 24, 2, 40, 5);
     ColorOptions := New( PRadioButtons, Init( Bounds,
                   NewSItem('~C~olor',
                   NewSItem('~M~onochrome',
                   NewSItem('~B~&W',
                   nil)))
                   ));
     Insert( ColorOptions );
     Bounds.Assign( 24, 1, 40, 2);
     Insert( New( PLabel, Init( Bounds, 'Color schemes',
            ColorOptions )));

constructor Load(var S: TStream);
     Creates a new TCluster object and loads the appropriate values (TView.Load
     and Value and Sel fields) from stream S.

function Mark(Item: Integer): Boolean; virtual;
     Mark is always overridden by the object that is derived from TCluster and
     is used to obtain the setting of the Item'th control in the cluster.  If
     the Item'th control is set, as for example, a check box is currently
     selected, then Mark should return True.  If the control is not currently
     set, then Mark should return False.
     See:  TCheckBoxes.Mark, TRadioButtons.Mark

procedure MovedTo(Item: Integer); virtual;
     MovedTo moves the active location within the cluster to the Item'th
     control.

procedure Press(Item: Integer); virtual;
     Press is always overridden by TCluster descendants to set or clear a check
     box item, or to set or clear a specific radio button.  

procedure SetData(var Rec); virtual;
     SetData copies Value field from Rec and draw's the cluster.  SetData is
     used in conjunction with GetData to access the dialog data.  See Chapter
     12, "Turbo Vision List Boxes" in the Borland Pascal Developer's Guide for
     an example.

procedure SetState(AState: Word; Enable: Boolean); virtual;
     TCluster.SetState passes its parameters to TView.SetState, and if the
     view's State is sfSelected , then calls TView.DrawView.

procedure Store(var S: TStream);
     Call's TView.Store(S) and then writes the contents of Value and Sel out to
     stream S. 
     See:  TCluster.Load, Chapter 15, "Streams" in the Borland Pascal
     Developer's Guide.


TCollection object
------------------------------------------------------------ 
Turbo Vision Hierarchy
  TObject
     TCollection
       TSortedCollection
       TStringCollection
       TResourceCollection

Discussion
          Collections provide a mechanism for storing and accessing arbitrary
     collections of data.  You can think of a collection as working like a
     dynamically sizeable array of data, that can be enlarged as your data
     requirements increase.  Several specialized collections are derived from
     TCollection, including TSortedCollection, TStringCollection and
     TResourceCollection.  The latter is used internally to the resource file
     mechanism and is not generally used by application programs.
          While collections are defined within Turbo Vision, you can also use
     collections in standard, non-Turbo Vision applications.
          In the description of the methods below, each method using an Index
     parameter checks to insure that the Index is in the valid range between 0
     and Count (the number of items in the collection).  If the Index is out
     range, these methods call TCollection.Error which, by default, halts the
     program with a run time error.  You can trap any collection error by
     overriding Error in your derived collection.
     See:  Chapter 14, "Collections" in the Borland Pascal Developer's Guide
     for complete details and a tutorial on the use of the TCollections object
     type.

Commonly Used Features
     TCollection.Count field, TCollection.Init, TCollection.Init, the access
     methods At, AtPut, AtDelete, AtFree, the iterators FirstThat, ForEach and
     LastThat, the IndexOf function, and the Load and Store methods.

Example
     See Chapter 14, "Collections" in the Borland Pascal Developer's Guide, for
     several examples.

Fields

Count: Integer;
     Holds the number of items currently stored in the collection.

Delta: Integer;
     Because one of the features of collections is that they can grow, Delta
     holds the number of elements by which the collection should be enlarged
     when the Count reaches the current maximum size specified by Limit.  When
     this occurs, Limit is increased by Delta and additional space is allocated
     for the necessary Item pointers.  Generally, Limit should initially be set
     to a sufficient size for most operations on the collection, and Delta
     should be set large enough so that expansion of the collection occurs
     infrequently to avoid the fairly intensive overhead of dynamically
     resizing the collection.
     See:  TCollection.Init, TCollection.Limit, TCollection.Items

Items: PItemList;
     Items points to an array that contains pointers to the individual items in
     the collection.

Limit: Integer;
     Holds the current number of elements allocated to the collection.
     See:  Delta, TCollection.Init

Methods

function At(Index : Integer): Pointer;
     Use At to access the collection as if it were an array.  At(Index) returns
     a pointer to the Index'th item in the array, where Index ranges from 0 up
     to Count.  
     See:  TCollection.IndexOf() as the inverse of At

procedure AtDelete(Index: Integer);
     AtDelete deletes the item at the location specified by Index, and slides
     all of the following items in the collection over to fill in the now
     vacant hole and decrements Count by 1.  AtDelete does not dispose of the
     actual item that was in the location.  Therefore, be sure to save a
     pointer to the item first, and then to separately dispose of the specific
     item using Dispose( ItemPtr, Done ).  
     See:  TCollection.AtFree , TCollection.Delete, TCollection.Free

procedure AtFree(Index: Integer);]
     AtFree works like AtDelete, except that the specific item being deleted is
     also disposed of.  If you do not need to retain a pointer to the specific
     item in the collection for future processing, you will probably want to
     use AtFree in place of AtDelete for deleting items from the collection. 
     See:TCollection.AtDelete, TCollection.Delete, TCollection.Free

procedure AtInsert(Index: Integer; Item: Pointer);
     AtInsert puts a new Item into the collection at the Index location by
     sliding all of the following items over by one position.  If adding the
     new element would exceed the size of the collection, TCollection.SetLimit
     is called to automatically expand the size.
     See:  TCollection.At,TCollection.AtPut, TCollection.SetLimit

procedure AtPut(Index: Integer; Item: Pointer);
     Use AtPut when you need to replace an existing item with a new item.  APut
     copies the new Item pointer to the location specified by Index.

procedure Delete(Item: Pointer);
     The items in a collection can be accessed via their index location or by
     way of the pointer to the item.  When you have a pointer to an item and
     wish to delete it, you can call Delete(Item) directly.  Alternatively, you
     can use the IndexOf() function to translate the pointer into an Index
     value and then use AtDelete, like this,
          AtDelete(IndexOf(Item));
     After an item is deleted, Count is decremented by 1.
     See:  TCollection.AtDelete, TCollection.AtFree, TCollection.Free,
     TCollection.IndexOf

procedure DeleteAll;
     Sets Count to 0, effectively deleting all items in the collection.
     See:  TCollection.AtDelete,TCollection. Delete

destructor Done; virtual;
     Always call a collection's Done method to dispose of each item and free up
     the memory used by the collection.

procedure Error(Code, Info: Integer); virtual;
Override:  As needed.
     All collection errors result in a call to Error, with error information
     passed in Code and Info.
     See: coXXXX constants.

function FirstThat(Test: Pointer): Pointer;
     FirstThat is one of the iterator functions and is normally used to search
     through the collection for a specific item.  Test should point to a
     locally defined far procedure, returning True when it matches the search
     pattern and False otherwise.  For each item in the collection until
     finding a match, FirstThat calls the Test function.
     See:  Chapter 14, "Collections" for a detailed example.

procedure ForEach(Action: Pointer);
     ForEach is an iterator function to scan through every item in the
     collection, and call the procedure specified by the Action pointer,
     passing to it a pointer to each individual item.  
     See:  Chapter 14, "Collections" for a detailed example.

procedure Free(Item: Pointer);
     This procedure is similar to Delete, except that Free also disposes of the
     memory occupied by the item.  Free is equivalent to calling,
          Delete(Item);
          FreeItem(Item);
     Although, Borland recommends not calling FreeItem directly.
     See:  TCollection.AtFree,TCollection. AtDelete, TCollection.Delete,
     TCollection.FreeAll

procedure FreeAll;
     Disposes of each item in the collection and sets Count to 0.

procedure FreeItem(Item: Pointer); virtual;
     When Item is a pointer to an individual item in the collection,
     FreeItem(Item) disposes Item by calling Dispose(PObject(Item), Done),
     using PObject to recast the pointer to a generic PObject.
     See:  TCollection.AtFree, TCollection.AtDelete, TCollection.Delete, Free

function GetItem(var S: TStream): Pointer; virtual;
     GetItem is used to read a single collection item from stream S and is
     automatically called by TCollection.Load.  You should not directly call
     this routine but should use Load instead.
     See:  TCollection.Load,  TCollection.PutItem, TCollection.Store

function IndexOf(Item: Pointer): Integer; virtual;
     Given a pointer to an Item, IndexOf returns the index position in the
     collection where the Item is located.  IndexOf is the opposite of
     At(Index) which returns a pointer to the item.
     See:  TCollection.At

constructor Init(ALimit, ADelta: Integer);
     TCollection.Init creates a new collection with space initially allocated
     for the number of elements specified by ALimit, and the ability to
     dynamically increase the size of the collection in ADelta increments.
     See:  MaxCollectionSize

procedure Insert(Item: Pointer); virtual;
     Inserts or adds the specified Item to the end of the collection and is
     equivalent to calling AtInsert(Item, Count).
     See:  TCollection.AtInsert

function LastThat(Test: Pointer); Pointer;
     LastThat searches backwards through the collection, beginning at the last
     item and moving forwards.  For each item, LastThat calls the function
     specified by Test, until Test returns a True result.  By having Test point
     to a function that makes a comparision between a search criteria and an
     item in the collection, you can use LastThat to quickly scan backwards in
     a collection.
     See:  TCollection.FirstThat, TCollection.ForEach

constructor Load(var S: TStream);
     Loads the entire collection from stream S, by calling TCollection.GetItem
     for each individual item in the collection.
     See:  TCollection.GetItem

procedure Pack;
     Use Pack to eliminate all nil pointers that may have been stored into the
     collection.

procedure PutItem(var S: TStream; Item: Pointer); virtual;
     Called by TCollection.Store to write an individual item to stream S.

procedure SetLimit(ALimit: Integer); virtual;
     Use SetLimit to manually adjust the number of elements allocated to the
     collection.  SetLimit operates by allocating a new Items array and copying
     the appropriate number of elements from the old Items array into the new
     array.
     See:  TCollection.Items, TCollection.Limit

procedure Store(var S: TStream);
     Writes the entire collection to stream S.
     See:  TCollection.Load, TCollection.PutItem


TCommandSet type
------------------------------------------------------------ 
Declaration:       
     TCommandSet = set of Byte;

Unit:     Views

Purpose:
In Turbo Vision, command codes are assigned values from 0 to 65,535, with
values in the range of 0 to 255 reserved for items that can be selectively
disabled.  TCommandSet is used to hold a set of up to 256 commands,
specifically those that can be disabled, and is used as a parameter for the
TView methods, EnableCommands, DisableCommands, GetCommands and SetCommands.
Listing TCMDSET.PAS illustrates the use of a TCommandSet type.
   1  { TCMDSET.PAS }
   2  { Example using TCommandSet, from TVSHELL8.PAS }
   3  var
   4    CommandsOn : TCommandSet;
   5    CommandsOff : TCommandSet;
   6    ...
   7    CommandsOn := [cmUseDOS, cmDelete];
   8    CommandsOff := CommandsOn;
   9  
  10    if  (SetUpData.ProgOptions and 2) = 2  then
  11      CommandsOff := CommandsOff - [cmUseDOS];
  12  
  13    if  (SetUpData.ProgOptions and 4) = 4  then
  14      CommandsOff := CommandsOff - [cmDelete];
  15  
  16    CommandsOn := CommandsOn - CommandsOff;
  17  
  18    DisableCommands( CommandsOff );
  19    EnableCommands( CommandsOn );


TDeskTop object
------------------------------------------------------------ 
Turbo Vision Hierarchy
  TObject
     TView
     TGroup
       TDeskTop
       TWindow
       TProgram

Discussion
     Each application has one TDeskTop object, pointed to by the global
     variable, DeskTop, that controls the area on the screen between the menu
     bar and the statusline. The TDeskTop object owns the TBackground that
     forms the backdrop for the screen, and typically owns other windows and
     dialogs that become inserted into the desktop during program execution.  

Commonly Used Features
     TDeskTop provides two functions for rearranging the windows:  Cascade and
     Tile.  Most applications will not need to manipulate the TDeskTop object
     other than to insert windows and control the operation of dialogs through
     the inherited ExecView method.  If you wish to change the background
     object, you'll need to derive a new TDeskTop object and override the
     InitBackground procedure described below.

Example
     Windows used by the application are normally inserted into the TDeskTop
     object.  For example, the TVSHELL sample program (see Chapters 11-12 of
     the Borland Pascal Developer's Guide) creates and inserts a directory
     window using the global DeskTop^ pointer, like this:

  GetExtent( Bounds );
  Bounds.B.Y := Bounds.B.Y - 2;  { We leave space for the status
                                   line }
  DirWindow := New( PDirectoryWindow, 
          Init(Bounds, 'Directory Listing', 0 ));
  DeskTop^.Insert(DirWindow);

     Modal dialog boxes are displayed on the desktop by calling the ExecView
     method, like this:

  { Let the user fiddle with the dialog box }
  Control := DeskTop^.ExecView (Dialog);
  if  Control <> cmCancel  then
  begin
     Dialog^.GetData( SetUpData );
     ...
  end;

     Non-modal dialog boxes are treated the same as a window and are inserted
     directly using Insert, as shown in the directory window example above.
          For an example of deriving a TDeskTop object to implement a new
     background, see TBackground.

Fields
Background: PBackground;
     Points to the TBackground object owned by this TDeskTop (note:  This field
     is omitted from the Borland documentation).

Methods
procedure Cascade(var R: TRect);
     Calling Cascade produces a "cascade effect" of all the windows currently
     owned by the desktop.  The effect is identical to that used by the IDE
     editor when multiple files are opened:  the window that appears farthest
     to the back is drawn to occupy the entire screen, and then each subsequent
     window is sized and positioned such that its upper left corner appears one
     line down and one character to the right of the window behind it.  
     See:  TDeskTop.Tile

constructor Init(var Bounds : TRect );
     Init creates a new TDeskTop with the size and position given by Bounds,
     and then calls InitBackground to create a new TBackground object.
     See:  TBackground, TDeskTop.InitBackground

procedure InitBackground; virtual;
Override:  As needed to create new TBackground objects
     InitBackground calls TBackground.Init to instantiate a new background
     object, and sets Background to point to the TBackground object.  If you
     wish to create a different appearing background thann the default
     background, there are two ways to go about it.  One is to merely insert a
     new TBackground object into the desktop so that it hides the previous
     desktop.  To do this, you would write,
          DeskTop^.Insert(New(PBackground, Init(Bounds, #FF));
     where Bounds defines the size and location of the new background object,
     and #FF is a hexadecimal character describing the pattern to use in
     drawing the new backdrop.  While this method is easy to implement, the
     original background continues to occupy memory.  A better approach is to
     use the method given as an example in the TBackground section, where a new
     TDeskTop object is derived and its InitBackground function is overridden
     to instantiate a new TBackground.  Using this approach, when the
     application runs, it automatically calls your TDesktop-derived object's
     InitBackground method, creating only one new background. 
     See:  TBackground for complete details.
     Important:  Borland's documentation describes a method called
     NewBackground to perform the operation of InitBackground.  However, in the
     actual implementation of Turbo Vision, NewBackground was replaced with
     InitBackground.

procedure HandleEvent(var Event: TEvent); virtual;
     TDeskTop.HandleEvent exists primarily to intercept the F6 key, used to
     cycle through the collection of windows that it owns.

function NewBackground: PView; virtual;
     This function, described in the Borland documentation does not exist.  See
     InitBackground.

procedure Tile(var R: TRect);
     Displays tileable windows, in tiled format, on to the screen.

procedure TileError; virtual;
Override:  As needed.
     If for some reason Turbo Vision is unable to rearrange and draw the
     windows in either cascaded or tiled format, Turbo Vision will call the
     TDeskTop.TileError procedure.  Normally, this procedure does nothing and
     returns.  However, if you wish to detect the condition and provide a
     message to the user, you can override this procedure.


TDialog object
------------------------------------------------------------ 
Turbo Vision Hierarchy
  TObject
     TView
       TGroup
          TWindow
            TDialog

Discussion
     Use TDialog to derive new types of dialog box objects.  In most cases, you
     will use the existing TDialog-type directly, and only reference its Init
     method.  Dialogs are then inserted into the desktop, or executed via
     DeskTop^.ExecView.  Generally, you will not need to access the dialog
     methods directly.  By default, dialog boxes cannot grow, but can be
     dragged or closed via a close icon.

Fields
     None

Methods
function GetPalette: PPalette; virtual;
Override:  As needed to define new color mappings.
     Returns a pointer to the CDialog palette, defining the basic color
     mappings for dialogs and all the controls that are inserted into dialogs. 


procedure HandleEvent(var Event: TEvent); virtual;
     Adds special processing of events to generate cmCancel, cmDefault, cmYes
     or cmNo commands in response to the appropriate inputs.

constructor Init(var Bounds: TRect; ATitle: TTitleStr);
     Passes the parameters Bounds and ATtitle to TWindow.Init to create a
     dialog box window with defaults set such that the dialog window cannot
     grow but can be dragged or closed.

function Valid(Command: Word): Boolean; virtual;
     If  the Command parameter equals cmCommand, then Valid returns True. 
     Otherwise, when Command is cmValid (or zero), Valid checks the Valid
     method of each of the controls that it owns in order to determine if the
     entire dialog was constructed satisfactorily.  All of the controls must
     return True in order for TDialog.True to return True.
     See:  TView.Valid, Chapters 16 and 19.


TDosStream object
------------------------------------------------------------ 
Turbo Vision Hierarchy
  TObject
     TStream
       TDosStream
          TBufStream

Discussion
     Use TDosStream for unbuffered stream file access (see also TBufStream). 
     For most applications you will probably prefer to use TBufStream for its
     faster, buffered file access.
     See  TStream, TBufStream, stXXXX constants

Commonly Used Features
     Generally, you will use the TDosStream.Init method to open a stream file
     for access, the TDosStream.Read and TDosStream.Write methods for
     performing input and output, and TDosStream.Done to close and dispose of
     the object.  For random access streams, you will use TBufStream.Seek to
     position the file pointer to the proper object record.

Example
     The use of TDosStream is nearly identical to TBufStream, without the
     buffering related methods.  See the TBufStream example and also Chapter
     15, "Streams" in the Borland Pascal Developer's Guide for information
     regarding the use of streams.

Fields
Handle: Word; { Read only }
     Contains the DOS file handle used to access the file containing the
     stream.

Methods
destructor Done; virtual;
     Closes the file and disposes of the stream object.

function GetPos: Longnt; virtual;
Override:  Never.
     Gives the stream's current position, in bytes, relative to the start of
     the stream.

function GetSize: Longint; virtual;
Override:  Never.
     Returns the total number of bytes in the stream.

constructor Init( Filename: FNameStr; Mode, Size : Word);
     Use Init to create and initialize a stream, using the parameters Filename
     for  the name of the file to open, and setting the Mode parameter to
     stCreate, stOpenRead, stOpenWrite or stOpen.

procedure Read( var Buf; Count: Word); virtual;
Override:  Never
     Use Read to read Count bytes from the stream and into the Buf parameter. 
     Read begins at the stream's current position (as determined by Seek or
     beginning at the end of the previous Read operation).
     See:  Chapter 15, "Streams", TOosStream.Seek, TDosStream.Write

procedure Seek(Pos : Longint); virtual;
Override:  Never.
     Positions the current stream position to Pos.  You can use Seek to
     implement random access to stream files (see Chapter 15, "Streams").  Be
     certain that if you are adding or multiplying values to compute the Pos
     parameter (for example, SizeOf(SomeObject) * Index), that you convert the
     parameters to Longint to avoid integer overflow errors.
     See:  Chapter 15, "Streams", TDosStream.GetPos,TDosStream.Read,
     TDosStream.Write

procedure Truncate; virtual;
Override:  Never.
     Use Truncate to delete all data following the current position in the
     stream.

procedure Write( var Buf; Count: Word); virtual;
Override:  Never.
     Use Write to copy Count bytes from the Buf parameter to the stream. 
     See:  Chapter 15, "Streams", TDosStream.Read


TDrawBuffer type
------------------------------------------------------------ 
Declaration:       
     TDrawBuffer = arrayu[0..MaxViewWidth-1] of Word;

Unit:     Views

Purpose:
     TDrawBuffer is used to create temporary storage areas for a line of text
     to be written to the screen where the low byte of each word contains the
     character value, and the high byte contains the video attribute byte.  You
     can use the Turbo Vision procedures, MoveBuf, MoveChar, MoveCStr, and
     MoveStr to set up the buffer and then use one of the TView method's
     WriteBuf or WriteLine within a Draw method to write the output to the
     screen.  Here's an example using TDrawBuffer:

var
  Buffer : TDrawBuffer;
  ...
  MoveStr(Buffer, 'Financial Results for FY1991', GetColor(1) );
  WriteLine( 1, 3, 28, 1, Buffer );

See:  TView methods WriteBuf and WriteLine.


TEmsStream object
------------------------------------------------------------ 
Turbo Vision Hierarchy
  TObject
     TStream
       TEmsStream

Discussion
     Use TEmsStream for storing stream files in EMS memory.  Important:  If you
     fail to call TEmsStream.Done, or if your program suffers an abnormal
     termination (i.e. "crashes"), the EMS will remain allocated.  The only way
     to recover allocated EMS is to reboot the computer.
     See:  TStream, TBufStream, TDosStream, stXXXX constants

Commonly Used Features
     Generally, you will use the TEmsStream.Init method to open a stream for
     access, the TEmsStream.Read and TEmsStream.Write methods for performing
     input and output, and TEmStream.Done to close and dispose of the object. 
     For random access streams, you will use TEmsStream.Seek to position the
     file pointer to the proper object reocrd.

Example
     See Chapter 15, "Streams" for a tutorial and examples of using TEmsStream.

Fields
Handle: Word; { Read only }
     Contains the EMS file handle used to access the stream.

PageCount: Word;
     Contains the total number of 16k byte pages allocated for the TEmsStream
     object.

Position: Longint;
     Contains the current location within the stream, beginning from byte 0.

Size: Longint;
     Contains the total size of the stream, in bytes.

Methods
destructor Done; virtual;
     Disposes and releases the EMS memory pages used by the stream.

function GetPos: Longnt; virtual;
Override:  Never.
     Gives the stream's current position, in bytes, relative to the start of
     the stream.

function GetSize: Longint; virtual;
Override:  Never.
     Returns the total number of bytes in the stream.

constructor Init( MinSize, MaxSize : Longint);
     Use Init to create an initialize the TEmsStream such that the stream will
     always have at least the minimum specified MinSize memory allocated to it.
     The exact allocation depends on the version of the EMS driver in use on
     your computer.  If your EMS driver is version 4.0 or greater, then MaxSize
     is ignored.  In 4.0 and greater, EMS blocks are dynamically resizeable so
     this parameter is ignored.  Prior to version 4.0, the EMS blocks could not
     be resized and in that case Init will initially try to allocate the entire
     MaxSize bytes.

procedure Read( var Buf; Count: Word); virtual;
Override:  Never
     Use Read to read Count bytes from the stream and into the Buf parameter. 
     Read begins at the stream's current position (as determined by Seek or
     beginning at the end of the previous Read operation).
     See:  Chapter 15, "Streams" in the Borland Pascal Developer's Guide,
     TEmsStream.Seek, TEmsStream.Write

procedure Seek(Pos : Longint); virtual;
Override:  Never.
     Positions the current stream position to Pos.  You can use Seek to
     implement random access to streams  (see Chapter 15, "Streams").  Be
     certain that if you are adding or multiplying values to compute the Pos
     parameter (for example, SizeOf(SomeObject) * Index), that you convert the
     parameters to Longint to avoid integer overflow errors.
     See:  Chapter 15, "Streams", TEmsStream.GetPos,TEmsStream.Read,
     TEmsStream.Write

procedure Truncate; virtual;
Override:  Never.
     Use Truncate to delete all data following the current position in the
     stream, resetting the current position to the end of the stream.

procedure Write( var Buf; Count: Word); virtual;
Override:  Never.
     Use Write to copy Count bytes from the Buf parameter to the stream. 
     See:  Chapter 15, "Streams", TEmsStream.Read


TEvent type
------------------------------------------------------------
Declaration:       
The TEvent type, as defined in Turbo Pascal 6.0, (C) Copyright 1991, by Borland
Intl:

   1  { TEVENT.PAS }
   2    PEvent = ^TEvent;
   3    TEvent = record
   4      What: Word;
   5      case Word of
   6        evNothing: ();
   7        evMouse: (
   8          Buttons: Byte;
   9          Double: Boolean;
  10          Where: TPoint);
  11        evKeyDown: (
  12          case Integer of
  13            0: (KeyCode: Word);
  14            1: (CharCode: Char;
  15                ScanCode: Byte));
  16        evMessage: (
  17          Command: Word;
  18          case Word of
  19            0: (InfoPtr: Pointer);
  20            1: (InfoLong: Longint);
  21            2: (InfoWord: Word);
  22            3: (InfoInt: Integer);
  23            4: (InfoByte: Byte);
  24            5: (InfoChar: Char));
  25    end;

Unit:       Drivers
Purpose:
     TEvent is a case variant record defining each type of event used in Turbo
Vision.  When a routine receives an event, it can look in the TEvent fields to
determine what type of event occurred and use other information provided to
appropriately process that event.  For example, when the TEvent.What field
contains evMouse, you can check TEvent.Buttonsto see which mouse button was
pressed (0=none, 1=left, 2=right).  The TEvent.Double flag is set if two mouse
clicks occurred within the DoubleDelay time interval.  Lastly, for each mouse
event, TEvent.Where contains the coordinates of the mouse.
     When the event record contains broadcast evMessage events, several variant
fields are provided for passing additional information with the message. 
InfoPtr can be used, for instance, to pass a pointer to a record or another
object. 
See:  Chapter 13, "More Turbo Vision Features" in the Borland Pascal
Developer's Guide for additional information regarding event processing, and
also see the HandleEvent method defined in various object types.

