EVENTS.
                             -------

 Turbo Vision applications are event-driven.  Events are occurrences to
 which the application must respond.  Traditional Turbo Pascal handling of
 events is achieved by reading some form of input and making decisions based
 on that input.  Turbo Vision deals with these tasks for the programmer.  It
 packages the input into Pascal records called 'events' and dispatches the
 events to the appropriate views in the program.

 A variant record of type TEvent is used (see page 376 of the Turbo Vision
 Guide).  The first field of the record is 'What' and this will be set to a
 word value representing one of four events: evNothing, evMouse, evKeyDown
 or evMessage.  A CASE statement is then used to determine the other fields
 appropriate to the event, with the fields associated with evKeyDown and
 evMessage themselves controlled by other CASE statements.

 Both outside events, such as mouse and keyboard events, and command events
 generated by inter-communicating views are stored and transmitted as TEvent
 records.

 The capture and execution of an event is automatically dealt with by the
 main processing loop of any instance of a type TApplication, the 'Run'
 method, which calls TGroup.Execute (see page 239).  This method repeatedly
 gets events using the 'GetEvent' method and handles them using the
 'HandleEvent' method.  In almost all cases it is the TProgram.GetEvent
 method which is called (page 271), unless this has been overridden.
 HandleEvent methods exist in the object hierarchy from TView through TGroup
 to TWindow, TDeskTop and TProgram.  Although TDeskTop.HandleEvent is seldom
 overridden, the other two frequently are, with TProgram.HandleEvent almost
 always overridden to introduce handling of commands that are specific to
 the user's own application.

 TProgram.GetEvent first checks if TProgram.PutEvent has generated a pending
 event and, if so, GetEvent returns that event.  If there is no pending
 event, GetEvent calls GetMouseEvent (page 345), a standard procedure.  If
 that returns evNothing, it then calls GetKeyEvent (page 344), another
 standard procedure.  If it also returns evNothing, indicating that there is
 no user input, GetEvent calls TProgram.Idle to allow 'background' tasks to
 be performed while the application is waiting for user input.  Before
 returning, GetEvent passes any evKeyDown and evMouseDown events to the
 StatusLine for it to map into associated evCommand hot-key events.

 The various kinds of event were mentioned in the second paragraph above and
 can now be defined in more detail.  A 'nothing' event is really a dead
 event.  When a Turbo Vision object finishes handling an event, it calls a
 method named ClearEvent, which sets the 'What' field back to evNothing,
 indicating that the event has been handled.

 There are four kinds of mouse event: an up or down click of either
 button, generating evMouseUp and evMouseDown respectively; a change of
 position, generating evMouseMove; or an 'auto' mouse event, periodically
 generated by Turbo Vision when the mouse is moved whilst a button is held
 down.

 The keyboard event simply generates evKeyDown and keeps track of which key
 was pressed.

 There are three kind of message events: commands, flagged by evCommand in
 the 'What' field; broadcasts, indicated by evBroadcast; and user messages,
 described by a user-defined constant.

 Events are sent first to the current 'modal' view, which is the view that
 currently defines the mode of operation.  For example, in the integrated
 development environment, there are editing, debugging, compiling and run
 modes.  When an application uses a modal dialog box, the dialog box object
 is the modal view and initiates the event handling.  Subsequently the event
 may be routed in one of three ways: positional, focused and broadcast.

 Positional events are almost always mouse events and are passed first to
 the modal view and then subsequently to the subviews in layer order, top
 downwards, called the Z-order.  This continues until a view is found which
 contains the position where the event occurred.  This continues until
 either there are no more subviews or there is no subview in the position
 where the event occurred.  Once the event has reached the object where the
 positional event took place, that object handles the event.



 EVENTS.WR1
 EVENTS.TXT
 31.3.91