REF XT_EVENT                                        Adrian Howard Apr 92

       COPYRIGHT University of Sussex 1990. All Rights Reserved.

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<      EVENT MANAGEMENT       >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<                             >>>>>>>>>>>>>>>>>>>>>>
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

Poplog provides  facilities  that allow  Toolkit  events to  be  handled
asynchronously. This REF file details these facilities and why they  are
needed

         CONTENTS - (Use <ENTER> g to access required sections)

  1   Introduction

  2   Format Of Procedures
      2.1   EventHandler Procedures
      2.2   Input Procedures
      2.3   TimeOut Procedures

  3   External Callback

  4   The Pop-11 Interface To Event Management
      4.1   LIB XT_EVENT
      4.2   LIB FAST_XT_EVENT

  5   Deferred Procedure Application



---------------
1  Introduction
---------------

Toolkit applications  are  event  driven.  A  typical  application  will
consist of some setup  code, followed by an  event loop which reads  and
processes events.

The  Toolkit  allows  applications  to  handle  events  by   registering
procedures, known as EventHandler procedures, which will be called  when
a particular  events  occur. Most  applications  will not  need  to  use
EventHandlers explicitly  -  the  higher  level  translation  management
mechanism (see  REF * XT_TRANS and  * XT_ACTION), or  a widget  supplied
callback list (see REF * XT_CALLBACK)  is usually more appropriate.  See
REF * XPT_XEVENT for more details of X event structures.

Non-X input sources can be  integrated with the Toolkit event  mechanism
by the  use  of  Input  procedures which  allow  Pop-11  devices  to  be
registered with an application. These are then called by alternate input
events.

See  REF * XT_GRAB  for  more   information  on  redirecting  input   to
individual widgets.

TimeOut procedures can be registered with an application. These will  be
executed when a specified period of time has elapsed by the action  of a
timer pseudo-event.

Poplog provides  facilities  that allow  Toolkit  events to  be  handled
asynchronously.

For more information on these mechanisms see chapter 7 of:

               X Toolkit Intrinsics - C Language Interface
                             X Window System
                         X Version 11, Release 4

        Copyright (C)  1985,  1986,  1987,  1988,  Massachusetts
        Institute of Technology,  Cambridge, Massachusetts,  and
        Digital Equipment Corporation, Maynard, Massachusetts.




-----------------------
2  Format Of Procedures
-----------------------

2.1  EventHandler Procedures
----------------------------
An EventHandler procedure is  executed when a  specified class of  event
occurs. It  should either  be an  appropriate external  procedure,  or a
Pop-11    procedure     that    has     been    coerced     with     the
XptExportEventHandler(Cached) procedures.

External procedures should be external function closures (for detail see
REF * EXTERNAL), or of  the type XptProcedure.  The external  procedures
should expect  to  be called  in  the  same format  as  the  following C
function prototype:

        typedef void(*XtEventHandler)
            (   Widget widget,
                XtPointer client_data,
               XEvent * xevent,
               Boolean * continue
           );

A Pop-11 EventHandler procedure P should expect to be called as follows:

        P(WIDGET, CLIENT_DATA, XEVENT) -> CONTINUE

WIDGET is the widget for which EventHandler is handling events.

CLIENT_DATA will  be  an arbitrary  data  object that  the  EventHandler
procedure was registered with. NOTE: Pop-11 EventHandler procedures  are
passed the data item itself, external procedures are passed a pointer to
the item.

XEVENT is an XptXEventPtr descriptor pointing to the event which  caused
the EventHandler  to  be called.  See  REF * XPT_XEVENT for  details  of
XEvent structures.

CONTINUE specifies whether any other  event handlers registered for  the
current event type should  be called. The other  event handlers are  not
called if  CONTINUE is  set to  <false>. NOTE:  external procedures  are
passed a pointer to a boolean value  which is, by default, true. If  the
external procedure  wishes to  stop  the processing  of the  event  they
should alter this value to false.

If a Pop-11 event handler procedure does not return a result, a value of
<true> for CONTINUE is assumed.

IMPORTANT NOTE: The  circumstances under  which the  Intrinsics may  add
event handlers to a widget is currently implementation dependent.  Thus,
setting CONTINUE to <false> may lead to portability problems.

It is an  error for external  EventHandlers to return  any items on  the
stack. It is an error for Pop-11 EventHandler procedures to return  more
than one item on the stack.

Care must be taken when using Pop-11 EventHandler procedures. It must be
remembered that the Pop-11 procedure is NOT what is registered with  the
intrinsics, the  COERCED  procedure  is.  If  you  are  coercing  Pop-11
procedures yourself, you must ensure that the COERCED procedure does not
become garbage during the lifetime  of the EventHandler procedure.  This
can be done by explicitly keeping track of the external function closure
returned by the coercion procedures XptExportEventHandler(Cached) or  by
supplying a <true> HOLD argument to them.



2.2  Input Procedures
---------------------
An Input procedure is  used to register a  new input (or output)  source
with an  application.  It  should  either  be  an  appropriate  external
procedure, or  a  Pop-11  procedure  that  has  been  coerced  with  the
XptExportInput(Cached)  procedures.  Input  procedures  are  added  with
XtAppAddInput and removed with XtRemoveInput.

External procedures should be external function closures (for detail see
REF * EXTERNAL), or of  the type XptProcedure.  The external  procedures
should expect  to  be called  in  the  same format  as  the  following C
function prototype:

        typedef void(*XtInputCallbackProc)
           (XtPointer client_data, int * source, XtInputId * inputid);

A Pop-11 Input procedure P should expect to be called as follows:

        P(CLIENT_DATA, DEV, INPUTID)

CLIENT_DATA will be an  arbitrary data object  that the Input  procedure
was registered with (see  XtAppAddInput). NOTE: Pop-11 Input  procedures
are passed  the  data  item itself,  external  procedures  are  passed a
pointer to the item.

DEV is the Pop-11 device that  is being used for input/output  (external
procedures are  passed a  pointer  to a  C-type file  descriptor,  not a
Pop-11 device).

INPUTID is a unique InputId  descriptor (returned when the procedure  is
registered) for this Input procedure. NOTE: Pop-11 procedures are passed
the actual descriptor, while external procedures are passed a pointer to
the descriptor.

It is an error for an Input procedure to return items on the stack.

Care must  be taken  when  using Pop-11  Input  procedures. It  must  be
remembered that the Pop-11 procedure is NOT what is registered with  the
intrinsics, the  COERCED  procedure  is.  If  you  are  coercing  Pop-11
procedures yourself, you must ensure that the COERCED procedure does not
become garbage during the lifetime of  the Input procedure. This can  be
done by  explicitly  keeping  track of  the  external  function  closure
returned  by  the  coercion  procedures  XptExportInput(Cached)  or   by
supplying a <true> HOLD argument to them.



2.3  TimeOut Procedures
-----------------------
A TimeOut procedure is executed after a given time interval has elapsed.
It should  either be  an  appropriate external  procedure, or  a  Pop-11
procedure  that  has  been  coerced  with  the  XptExportTimeOut(Cached)
procedures.  TimeOut  procedures  are  added  with  XtAppAddTimeOut  and
removed with XtRemoveTimeOut.

External procedures should be external function closures (for detail see
REF * EXTERNAL), or of  the type XptProcedure.  The external  procedures
should expect  to  be called  in  the  same format  as  the  following C
function prototype:

        typedef void(*XtTimerCallbackProc)
            (XtPointer client_data, XtIntervalId * intervalid);

A Pop-11 TimeOut procedure P should expect to be called as follows:

        P(CLIENT_DATA, INTERVALID)

CLIENT_DATA will be an arbitrary data object that the TimeOut  procedure
was  registered  with  (see   XtAppAddTimeOut).  NOTE:  Pop-11   TimeOut
procedures are  passed the  data item  itself, external  procedures  are
passed a pointer to the item.

INTERVALID  is  a  unique  IntervalId  descriptor  (returned  when   the
procedure is  registered)  for  this  TimeOut  procedure.  NOTE:  Pop-11
procedures are passed the  actual descriptor, while external  procedures
are passed a pointer to the descriptor.

It is an error for a TimeOut procedure to return items on the stack.

Care must be  taken when  using Pop-11  TimeOut procedures.  It must  be
remembered that the Pop-11 procedure is NOT what is registered with  the
intrinsics, the  COERCED  procedure  is.  If  you  are  coercing  Pop-11
procedures yourself, you must ensure that the COERCED procedure does not
become garbage during the lifetime of the TimeOut procedure. This can be
done by  explicitly  keeping  track of  the  external  function  closure
returned by  the  coercion  procedures  XptExportTimeOut(Cached)  or  by
supplying a <true> HOLD argument to them.




--------------------
3  External Callback
--------------------

Since Pop-11 Input, TimeOut, and EventHandler procedures are called from
outside Poplog they use a special "external callback" mechanism. This is
explained in REF * XT_CALLBACK. You  should read the following  sections
from REF * XT_CALLBACK if you have not done so already:

     #  Overview - External Callbacks
     #  Generic External Callbacks Under The Poplog X Interface
     #  Possible Problems With Default External Callback Coercion




-------------------------------------------
4  The Pop-11 Interface To Event Management
-------------------------------------------

The library LIB * XT_EVENT provides the Pop-11 interface to the  various
Intrinsics related to event management. The library  LIB * FAST_XT_EVENT
(loaded by LIB * XT_EVENT)  provides non-checking versions  of the  same
procedures in addition to supporting  the coercion of Pop-11  procedures
into structures  that can  be  passed as  external Input,  TimeOut,  and
EventHandler procedures.

The structure of arguments and  results for the following procedures  is
discussed in REF * XPT_TYPES.


4.1  LIB XT_EVENT
-----------------

XtBuildEventMask(widget) -> event_mask                       [procedure]
        Retrieves the  event  mask  event_mask  of  the  widget  widget.
        event_mask specifies the event  types which widget can  receive.
        Possible values for event_mask are given in INCLUDE * XPT_XEVENT
        (see REF * XPT_XEVENT).


XtSetSensitive(widget, bool)                                 [procedure]
        Sets the sensitivity state of the widget widget to bool.

        A  widgets  sensitivity   is  controlled  by   the  two   fields
        "sensitive" and  "ancestor_sensitive"  in the  XptCorePart  of a
        widget  (see  REF * XPT_WIDGETTYPES).  The  "ancestor_sensitive"
        field is <false> if the "sensitive" field of the widgets  parent
        is <false>. These  fields are accessible  by the boolean  widget
        resources "XtN sensitive" and "XtN ancestorSensitive" (NOTE: the
        latter resource should only be queried, not altered).

        A widget  is  considered to  be  insensitive if  either  of  the
        following conditions hold:

          # The widgets parent is insensitive.
            (the widgets "ancestor_sensitive" field is <false>)

          # The widget is not sensitive.
            (the widgets "sensitive" field is <false>)

        When a  widget  is insensitive  it  does not  receive  KeyPress,
        KeyRelease,    ButtonPress,     ButtonRelease,     MotionNotify,
        EnterNotify, LeaveNotify,  FocusIn,  and FocusOut  events.  Many
        widgets assume a different appearance when they are  insensitive
        (for example, they might become grey or stippled).

        When XtSensitive is called it sets the "XtN sensitive" field  of
        widget to bool. If  widget is a composite  widget, it then  sets
        the "ancestor_sensitive" fields of any children of widget to the
        appropriate value, depending  on the "ancestor_sensitive"  field
        of widget. This change propagates down the widget tree  ensuring
        that   if   a    parent   has   a    <false>   "sensitive"    or
        "ancestor_sensitive"   field,    its   children    have    their
        "ancestor_sensitive" fields set to <false>.

        NOTE: The procedure  XtSetSensitive uses  XtSetValues to  change
        the "sensitive"  and "ancestor_sensitive"  fields of  widgets. A
        widgets "set_values" method should take care of whatever display
        actions are needed.


XtIsSensitive(widget) -> bool                                [procedure]
        Reports whether the widget  widget can receive keyboard,  focus,
        and  pointer  events.  It  returns  <true>  if  both  the   "XtN
        sensitive" and "XtN ancestorSensitive"  resources of the  widget
        widget  are   <true>,  otherwise   <false>  is   returned.   See
        XtSetSensitive for details.


XtAddEventHandler(widget, event_mask, nonmaskable,           [procedure]
            widentproc, client_data)
        Registers the EventHandler procedure  referred to by  widentproc
        on the widget  widget, altering  widget so it  will receive  the
        specified events.

        event_mask  specifies   the   events  which   will   cause   the
        EventHandler to be  called. Possible values  for event_mask  are
        given in INCLUDE * XPT_XEVENT (see REF * XPT_XEVENT).

        If nonmaskable is <false> then  the EventHandler referred to  by
        widentproc will  NOT be  called when  non-maskable events  occur
        (ie, GraphicsExpose, NoExpose, SelectionClear, SelectionRequest,
        SelectionNotify, ClientMessage,  and  MappingNotify).  Otherwise
        the EventHandler procedure will also be called when these events
        occur.

        client_data can be any Pop-11 object.  It will be passed to  the
        EventHandler referred to by widentproc when it is executed.

        If widentproc refers to a  Pop-11 procedure it is  automatically
        coerced into an  external form, along  with client_data, by  the
        procedure  XptExportEventHandlerCached.  A   reference  to   the
        (possible coerced) EventHandler is kept  by widget so it  cannot
        become garbage during widget's lifetime.

        If the procedure referred to by widentproc is already registered
        with  the  same  client_data   then  the  events  specified   by
        event_mask and nonmaskable are selected for in ADDITION to those
        selected when the procedure was registered previously.

        If more  than  one event  handler  is  added to  a  widget  with
        XtAddEventHandler,  their  execution  order  is   implementation
        specific.


XtAddRawEventHandler(widget, event_mask, nonmaskable,        [procedure]
            widentproc, client_data)
        As for  XtAddEventHandler,  but  the specified  events  are  not
        selected for in widget (unless they are selected already).


XtInsertEventHandler(widget, event_mask, nonmaskable,        [procedure]
            widentproc, client_data, listposition)
        As for  XtAddEventHandler,  but  allows  the  execution  of  the
        EventHandler to  be  specified  in relation  to  any  previously
        registered event  handlers. The  listposition position  argument
        can take one of two values specified in  INCLUDE * XT_CONSTANTS.
        If its value is XtListHead then the Eventhandler referred to  by
        widentproc will  be executed  before all  previously  registered
        EventHandlers. If  its  value  is XtListTail  then  it  will  be
        executed after all previously registered EventHandlers.


XtInsertRawEventHandler(widget, event_mask, nonmaskable,     [procedure]
            widentproc, client_data, listposition)
        As for XtInsertEventHandler,  but the specified  events are  not
        selected for in widget (unless they are selected already).


XtRemoveEventHandler(widget, event_mask, nonmaskable,        [procedure]
            widentproc, client_data)
        Stops  the   (previously  registered)   EventHandler   procedure
        specified by widget,  widentproc and  client_data receiving  the
        events specified by event_mask and nonmaskable, altering  widget
        so it will no longer receive the specified events if necessary.

        The arguments are as for XtAddEventHandler. If widentproc refers
        to a  Pop-11  procedure  it is  automatically  coerced  into  an
        external  form,   along   with  its   associated   client   data
        client_data, by the procedure XptExportEventHandlerCached.

        Any references  to the  EventHandler in  the widget  widget  are
        dropped if the procedure cannot receive events after the call to
        XtRemoveEventHandler,  enabling  the  procedure  to  be  garbage
        collected if it is not referenced elsewhere.

        If  the  specified  EventHandler  cannot  be  located  then  the
        procedure does nothing.


XtRemoveRawEventHandler(widget, event_mask, nonmaskable,     [procedure]
            widentproc, client_data)
        As for  XtRemoveEventHandler, but  the  widget widget  is  never
        stopped from receiving the specified events.


XtAppAddInput(appcontext, dev, mask, widentproc,             [procedure]
                client_data) -> inputid
        Registers the Pop-11 device dev as  a source of events with  the
        application context appcontext. When the conditions specified by
        mask occur on dev then an alternate input event is placed on the
        event queue of appcontext which  will cause the Input  procedure
        referred to by widentproc to be called.

        mask is a integer bitmask specifying the conditions under  which
        dev will  generate  an event.  The  legal values  for  mask  are
        operating system dependent. Legal values for Unix systems are:

          # XtInputExceptMask : An input exception.
          # XtInputReadMask : A pending read condition.
          # XtInputWriteMask : A pending write condition.

        The   values   of    these   constants   can    be   found    in
        INCLUDE * XT_CONSTANTS (see REF * XT_CONSTANTS).

        Under VMS Poplog, mask must  be XtInputReadMask and dev must  be
        either a terminal or a mailbox.

        widentproc refers to  an Input  procedure which  will be  called
        with the client  data client_data  when the  event specified  by
        mask occurs on the device dev. If widentproc refers to a  Pop-11
        procedure  it,  and  client_data,   will  be  coerced  into   an
        appropriate external form with the XptExportInput procedure.

        inputid is  a unique  InputId descriptor  identifying the  event
        source that was added by XtAppAddInput. Unless inputid is  going
        to be  used  with  XtRemoveInput it  can  be  discarded  since a
        reference to it is kept in the application context appcontext.

        A reference to the  (possible coerced) Input procedure  referred
        to by widentproc is also kept by inputid to prevent it  becoming
        garbage collected during the lifetime of the Input procedure.


XtRemoveInput(inputid)                                       [procedure]
        Removes the Input procedure referred  to by inputid as a  source
        of events.  This  procedure is  the  default destroy  action  of
        InputId records.

        The reference to inputid  in its associated application  context
        is removed by calling this procedure, as is the reference to the
        (possibly coerced)  Input  procedure  in  inputid.  This  allows
        inputid and its associated Input procedure to become garbage  if
        they  are  not  referenced  elsewhere.  See  XtAppAddInput   for
        details.


XptInputIdToDevice(inputid) -> dev                           [procedure]
        Returns the  Pop-11  device  dev  associated  with  the  InputId
        descriptor inputid (as returned by XtAppAddInput).


XtAppAddTimeOut(appcontext, int, widentproc, client_data)    [procedure]
                -> intervalid
        This procedure  causes  the  TimeOut procedure  referred  to  by
        widentproc to  be added  to the  application context  appcontext
        with client data client_data. When int milliseconds have elapsed
        a timer pseudo-event is placed on the event queue of  appcontext
        which will case the Timer procedure referred to by widentproc to
        be called, and then removed.

        If  widentproc  refers  to  a  Pop-11  procedure  it,  and   its
        associated client_data,  will  be coerced  into  an  appropriate
        external form with the XptExportTimeOut procedure.

        intervalid is  a unique  IntervalId descriptor  identifying  the
        TimeOut procedure added by XtAppAddTimeOut. Unless intervalid is
        going to be used with XtRemoveTimeOut it can be discarded  since
        a reference to it is kept in the application context appcontext.

        A reference to the (possible coerced) TimeOut procedure referred
        to by  widentproc  is also  kept  in intervalid  to  prevent  it
        becoming garbage collected before it is executed.


XtRemoveTimeOut(intervalid)                                  [procedure]
        Removes the  TimeOut  callback identified  by  intervalid.  This
        procedure  is   the  default   destroy  action   of   IntervalId
        descriptors. NOTE: the procedure is automatically called after a
        TimeOut procedures has been triggered.

        The  reference  to  intervalid  in  its  associated  application
        context  is  removed  by  calling  this  procedure,  as  is  the
        reference  to  the  (possibly  coerced)  TimeOut  procedure   in
        intervalid. This allows  intervalid and  its associated  TimeOut
        procedure  to  become  garbage   if  they  are  not   referenced
        elsewhere. See XtAppAddTimeOut for details.


XtAppPending(appcontext) -> inputmask                        [procedure]
        Returns an integer inputmask  indicating any pending events  for
        the application  context appcontext.  If  their are  no  pending
        events then inputmask will return  zero, and the output  buffers
        of all the displays registered with appcontext are flushed.

        If there  are  pending  events inputmask  will  be  the  logical
        inclusive OR of:

          XtIMXEvent
              If there is a pending X event.

          XtIMTimer
              If there is a TimeOut procedure waiting to be executed
              because its time interval has expired.

          XtIMAlternateInput
              If there is an Input procedure waiting to be executed.

        The values of XtIMEvent,  XtIMTimer, and XtIMAlternateInput  are
        defined in  INCLUDE * XT_CONSTANTS.PH  (see  REF * XT_CONSTANTS)
        along  with  the  constant  XtIMAll  which  corresponds  to  the
        inclusive OR of the above three constants.


XtAppPeekEvent(appcontext, xeventptr) -> bool                [procedure]
        Looks at the next event in the event queue of appcontext without
        removing that event from the queue.

        If their are no events in  the queue then the procedure  flushes
        all  the  output  buffers   of  the  displays  registered   with
        appcontext and  waits for  an X  event to  appear on  the  input
        queue. Any TimeOut callbacks that  occur during this period  are
        executed immediately.

        If the next event on the queue is a normal X event, it is copied
        into  the  XEvent  structure  pointed  to  by  the  XptXEventPtr
        descriptor xeventptr and <true> is returned.

        If the next  event on  the queue is  due to  an alternate  input
        source (ie,  something  to be  handled  by an  Input  procedure)
        XtAppPeekEvent returns <false>.


XtAppNextEvent(appcontext, xeventptr)                        [procedure]
        Returns the next event from  the event queue of the  application
        context appcontext.  The event  is removed  from the  queue  and
        copied into the XEvent structure pointed to by the  XptXEventPtr
        descriptor xeventptr.

        If their are no events in  the queue then the procedure  flushes
        all  the  output  buffers   of  the  displays  registered   with
        appcontext and  waits for  an X  event to  appear on  the  input
        queue. This event  is then  removed and copied  into the  XEvent
        structure pointed  to  by  xeventptr, as  described  above.  Any
        TimeOut or Input callbacks that occur during the waiting  period
        are executed immediately.

        The  events  returned  in  xeventptr  can  be  dispatched   with
        XtDispatchEvent.

        Most programs  do not  need  this much  control over  the  event
        dispatching  mechanism  and  will   use  XtAppMainLoop  or   the
        asynchronous     application     context     mechanism      (see
        XptAsyncAppContext).


XtDispatchEvent(xeventptr) -> bool                           [procedure]
        Executes any EventHandler procedures  registered for the  XEvent
        pointed to by  the XptXEventPtr descriptor  xeventptr. A  <true>
        value  is  returned  if  any  EventHandler(s)  were  executed. A
        <false> value is returned if no EventHandler was registered  for
        the specified event.

        This procedure  is  usually  called  with  event  structures  as
        returned by XtAppNextEvent, but it can also be used to  dispatch
        user-constructed events.

        NOTE: since the entire translation manager is implemented as  an
        EventHandler procedure,  a  call to  XtDispatchEvent  may  cause
        Action procedures  to be  called if  a translation  matches  the
        event being dispatched.  See REF * XT_TRANS and  REF * XT_ACTION
        for details of the translation manager.

        See REF * XT_GRAB for details on how the delivery of events  can
        be   affected    by   modal    widget   cascades.    Also    see
        XtLastTimestampProcessed in REF * XT_GRAB.


XtAppProcessEvent(appcontext, inputmask)                     [procedure]
        Process a SINGLE event  of the type  specified by inputmask  for
        the application context appcontext. If an event of the specified
        type is not  present, the  procedure blocks until  there is.  If
        more than one of the specified event type(s) is available, it is
        undefined which one will be processed.

        inputmask will be the logical inclusive OR of:

          XtIMEvent
              If an X Event should be processed by XtDispatchEvent.

          XtIMTimer
              If a timer pseudo-event should be processed by its
              associated TimeOut procedure (see XtAppAddTimeOut).

          XtIMAlternateInput
              If an alternate-input event should be processed by its
              associated Input procedure (see XtAppAddInput).

        The values of XtIMEvent,  XtIMTimer, and XtIMAlternateInput  are
        defined in  INCLUDE * XT_CONSTANTS.PH  (see  REF * XT_CONSTANTS)
        along  with  the  constant  XtIMAll  which  corresponds  to  the
        inclusive OR of the above three constants.


XptAppTryEvents(appcontext)                                  [procedure]
XptAppTryEvents(appcontext, false)
XptAppTryEvents(appcontext, true) -> event_processed
        Process  any   pending  events   in  the   application   context
        appcontext, returning when  there are no  more events ready  for
        processing.

        This procedure takes an optional boolean second argument,  which
        when true  causes the  event_processed  result to  be  returned;
        event_processed is true if any events were processed, and  false
        otherwise.


XptSyncDisplay(displayptr)                                   [procedure]
        Tries  to  ensure  that  the  display  given  by  displayptr  is
        quiescent.

        Repeatedly calls XSync on the display and XptAppTryEvents on its
        application context,  quitting only  when  the latter  fails  to
        process any further events.


XtAppMainLoop(appcontext)                                    [procedure]
        Repeatedly process the events arising in the application context
        appcontext.  This   procedure   can  only   be   terminated   by
        interruption   or   abnormal   exit   from   a   callback    (eg
        "exitfrom(fast_XtAppMainLoop)"). This procedure  is roughly  the
        equivalent of  repeatedly  calling  XtAppNextEvent  followed  by
        XtAppProcessEvent. You may  wish to use  the asynchronous  event
        handling capability given by XptAsyncAppContext instead of using
        this procedure.


XptAsyncAppContext(appcontext) -> bool_or_trap_p             [procedure]
bool_or_trap_p -> XptAsyncAppContext(appcontext)
        Controls asynchronous  processing  of  toolkit  events  for  the
        application context appcontext.

        If bool is <false> then asynchronous processing is disabled.

        If trap_p  is  supplied,  asynchronous  processing  is  enabled.
        trap_p should be a Pop-11  procedure which will be run  whenever
        there  are  events  pending   for  appcontext.  trap_p  is   run
        asynchronously, i.e. the  inside whatever  other procedures  the
        system is currently  executing. Detection of  pending events  is
        achieved either by waiting on appcontext with  XtAppProcessEvent
        during Poplog  wait  states,  or continuously  polling  it  with
        XtAppPending when Poplog is executing  program code. A value  of
        <true> for bool is equivalent to the procedure

            fast_XptAppTryEvents(%appcontext%)

        which is the  normal way of  processing events (although  <true>
        enables the  system to  optimise  performance and  is  therefore
        always preferable to the above).

        Note that XptDefaultSetup enables asynchronous processing  (with
        <true>)  on   XptDefaultAppContext.   See  Event   Handling   in
        REF * XTOOLKIT for a discussion of asynchronous event handling.



4.2  LIB FAST_XT_EVENT
----------------------

fast_XtBuildEventMask(widget) -> event_mask                  [procedure]
fast_XtSetSensitive(widget, bool)                            [procedure]
fast_XtIsSensitive(widget) -> bool                           [procedure]
fast_XtAddEventHandler(widget, event_mask, nonmaskable,      [procedure]
                            widentproc, client_data)
fast_XtAddRawEventHandler(widget, event_mask, nonmaskable,   [procedure]
                            widentproc, client_data)
fast_XtInsertEventHandler(widget, event_mask, nonmaskable,   [procedure]
                    widentproc, client_data, listposition)
fast_XtInsertRawEventHandler(widget, event_mask, nonmaskable,[procedure]
                    widentproc, client_data, listposition)
fast_XtRemoveEventHandler(widget, event_mask, nonmaskable,   [procedure]
                            widentproc, client_data)
fast_XtRemoveRawEventHandler(widget, event_mask, nonmaskable,[procedure]
                            widentproc, client_data)
fast_XtAppAddInput(appcontext, dev, mask, widentproc,        [procedure]
                                client_data) -> inputid
fast_XtRemoveInput(inputid)                                  [procedure]
fast_XtAppAddTimeOut(appcontext, int, widentproc,            [procedure]
                                client_data) -> intervalid
fast_XtRemoveTimeOut(intervalid)                             [procedure]
fast_XtAppPending(appcontext) -> inputmask                   [procedure]
fast_XtAppPeekEvent(appcontext, xeventptr) -> bool           [procedure]
fast_XtAppNextEvent(appcontext, xeventptr)                   [procedure]
fast_XtDispatchEvent(xeventptr) -> bool                      [procedure]
fast_XtAppProcessEvent(appcontext, inputmask)                [procedure]
fast_XptAppTryEvents(appcontext)                             [procedure]
fast_XptAppTryEvents(appcontext, false)
fast_XptAppTryEvents(appcontext, true) -> event_processed
fast_XtAppMainLoop(appcontext)                               [procedure]
        Non-checking versions of the procedures in LIB * XT_EVENT. There
        operation is the same except that:

            # There is no checking for valid arguments.
            # NO coercion of Pop-11 procedures is performed.

        These procedures should only be used in fully debugged programs.
        See REF * XTOOLKIT  for  full details  of  the Poplog  X  naming
        conventions for non-checking and checking procedures.


XptImportInputId(exptrclass) -> inputid_or_false             [procedure]
inputid_or_false -> XptImportInputId() -> exptrclass
        Given an external pointer class  record pointing to an  external
        XtInputId structure, this procedure  returns the Pop-11  inputid
        record for it (creating a  new one if necessary). If  exptrclass
        is a null pointer then <false> is returned.

        If the updater is given <false> it coerces it to a null external
        pointer. If it is given a inputid it returns an external pointer
        class record that refers to that XtInputId. NOTE: Since  inputid
        is such an external pointer class record, the updater acts  like
        identfn when given a non-false value.

        This routine can  be used as  a conversion procedure  in a  type
        specification (see REF * DEFCLASS).


XptImportIntervalId(exptrclass) -> intervalid_or_false       [procedure]
intervalid_or_false -> XptImportIntervalId() -> exptrclass
        As for XptImportInputId, but  converts between external  pointer
        class records  and Pop-11  intervalid  records (as  returned  by
        XtAppAddTimeOut).


XptExportEventHandler(widentproc, client_data, hold)         [procedure]
                                        -> (efc, item)
        This  procedure  coerces   the  Pop-11  EventHandler   procedure
        referred to  by  widentproc,  and  an  arbitrary  Pop-11  object
        client_data, into an external function closure efc and a  Pop-11
        item  item,  that  are  suitable  to  be  passed  as  a  toolkit
        EventHandler-procedure/client-data pair.

        IMPORTANT  NOTE:  If  the  procedure  is  called  on   different
        occasions with  the same  widentproc  and client_data,  it  will
        return DIFFERENT external  function closures  which perform  the
        same operation.

        If the boolean argument hold is  <true> then a reference to  efc
        is added to the  fixed hold list to  prevent it getting  garbage
        collected. To remove the efc from the list, use free_fixed_hold.
        See REF * EXTERNAL_DATA for more details.

        It should  be  noted  that  widget  records  attempt  to  keep a
        reference    to    their     EventHandler    procedures     (see
        REF * XptDescriptor) so  the user  does not  have to  have  hold
        <true>, or keep a reference to the efc, when the efc is added as
        a toolkit EventHandler procedure.

        The procedure operates by creating an external function  closure
        of the  procedure XptEventHandlerWrapper.  The value  of efc  is
        given by:

            exfunc_export(
                XptEventHandlerWrapper(%widentproc, client_data%),
                XptCallbackFlags,
                hold
            );

        Since the client_data  is passed  to widentproc by  the call  to
        XptEventHandlerWrapper the EventHandler client data item has  no
        effect in  the toolkit  EventHandlers calls.  item is  therefore
        always returned containing a value of <false>.


XptExportInput(widentproc, client_data, hold)                [procedure]
                                        -> (efc, item)
        This procedure coerces the Pop-11 Input procedure referred to by
        widentproc, and an arbitrary Pop-11 object client_data, into  an
        external function closure efc and  a Pop-11 item item, that  are
        suitable  to  be   passed  to   the  Intrinsics   as  an   Input
        procedure/client-data  pair.  Its  operation  is  the  same   as
        XptExportEventHandler,     except     that     the     procedure
        XptInputWrapper, instead of  XptEventHandlerWrapper, is used  to
        create efc.


XptExportTimeOut(widentproc, client_data, hold)              [procedure]
                                        -> (efc, item)
        This procedure coerces the Pop-11 TimeOut procedure referred  to
        by widentproc, and an arbitrary Pop-11 object client_data,  into
        an external function closure  efc and a  Pop-11 item item,  that
        are suitable  to  be  passed  to the  Intrinsics  as  a  TimeOut
        procedure/client-data  pair.  Its  operation  is  the  same   as
        XptExportEventHandler,     except     that     the     procedure
        XptTimeOutWrapper, instead of XptEventHandlerWrapper, is used to
        create efc.


XptExportEventHandlerCached(widentproc, client_data, hold)   [procedure]
                                        -> (efc, item)
        This  procedure  coerces   the  Pop-11  EventHandler   procedure
        referred to  by  widentproc,  and  an  arbitrary  Pop-11  object
        client_data, into an external function closure efc and a  Pop-11
        item item, that  are suitable  to be passed  as an  EventHandler
        procedure/client-data pair to the Intrinsics.

        The   arguments   and   results   are   as   for   a   call   to
        XptExportEventHandler, the difference  being that the  resultant
        external  function  closure  efc  is  cached.  This  means  that
        different calls to  XptExportEventHandlerCached WILL return  the
        same external function closure efc;  if the same widentproc  and
        client_data are used  (the cache considers  the arguments to  be
        the same if -sys_=- returns <true> when applied to them).

        The entry in the cache for efc becomes garbage when efc  becomes
        garbage.

        XptExportEventHandlerCached is the  default procedure used  when
        coercing Pop-11 EventHandler procedures. It should be noted that
        widget records attempt to keep a reference to their EventHandler
        procedures (REF * XptDescriptor for  details) so  the user  does
        not have to have  hold <true>, or keep  a reference to the  efc,
        when the efc is added as a toolkit EventHandler procedure.


XptExportInputCached(widentproc, client_data, hold)          [procedure]
                                        -> (efc, item)
        As  for  XptExportEventHandlerCached,  except  that  it  coerces
        between Pop-11 Input procedures and external function closures.


XptExportTimeOutCached(widentproc, client_data, hold)        [procedure]
                                        -> (efc, item)
        As  for  XptExportEventHandlerCached,  except  that  it  coerces
        between  Pop-11   TimeOut  procedures   and  external   function
        closures.


XptEventHandlerWrapper(exptrclass, widentproc, client_data)  [procedure]
        Closures of the procedure XptEventHandlerWrapper are used by the
        XptExportEventHandler(Cached)  procedures  to  create   external
        function closures  that  can  be used  as  toolkit  EventHandler
        procedures. For more details  of external function closures  see
        REF * EXTERNAL.

        exptrclass should be an  external pointer class record  pointing
        to an instance of the following structure:

            l_typespec extdata {
                widget      :XptWidget,
                client_data :XptPointer,
                event       :XptXEventPtr,
                contin      :exptr.:XptBoolean,
            };

        The "widget"  field  of  the above  structure,  the  client_data
        passed to XptEventHandlerWrapper, and  the "event" field of  the
        above structure are then  pushed onto the  stack, ready for  the
        call of the  procedure referred to  by widentproc.  client_data,
        which can  be any  Pop-11 object,  replaces whatever  is in  the
        "client_data" field of the structure referred to by exptrclass.

        The procedure  referred  to  by widentproc,  which  should  be a
        Pop-11 EventHandler procedure,  is then  executed by  a call  to
        XptCallbackHandler with a TYPE of "event".

        If the procedure referred to by widentproc returns a result,  it
        is placed in the "contin" field  of the structure pointed to  by
        exptrclass before XptEventHandlerWrapper exits.


XptInputWrapper(exptrclass, widentproc, client_data)         [procedure]
        Closures of  the  procedure  XptInputWrapper  are  used  by  the
        XptExportInput(Cached) procedures  to create  external  function
        closures that can be used as toolkit Input procedures. For  more
        details of external function closures see REF * EXTERNAL.

        exptrclass should be an  external pointer class record  pointing
        to an instance of the following structure:

            l_typespec extdata {
                client_data :XptPointer,
                file        :exptr.:int,
                inputid     :exptr.:XptInputId,
            };

        The following items are  then place on the  stack ready for  the
        call of the procedure referred to by widentproc:

          # The client_data passed to XptInputWrapper.

          # The Pop-11 device associated with the InputId descriptor in
            the "inputid" field of the structure referred to by
            exptrclass.

          # The contents of the "inputid" field (ie, an InputId
            descriptor).

        client_data, which can be  any Pop-11 object, replaces  whatever
        is in  the "client_data"  field.  In a  similar way  the  Pop-11
        device associated with the  InputId descriptor in the  "inputid"
        field replaces the external file descriptor in the "file" field.

        The procedure  referred  to  by widentproc,  which  should  be a
        Pop-11  Input  procedure,  is  then   executed  by  a  call   to
        XptCallbackHandler with a TYPE of "input".


XptTimeOutWrapper(exptrclass, widentproc, client_data)       [procedure]
        Closures of  the procedure  XptTimeOutWrapper  are used  by  the
        XptExportTimeOut(Cached) procedures to create external  function
        closures that can  be used  as toolkit  TimeOut procedures.  For
        more details of external function closures see REF * EXTERNAL.

        exptrclass should be an  external pointer class record  pointing
        to an instance of the following structure:

            l_typespec extdata {
                client_data :XptPointer,
                intervalid  :exptr.:XptIntervalId,
            };

        The following items are  then place on the  stack ready for  the
        call of the procedure referred to by widentproc:

          # The client_data passed to XptTimeOutWrapper.
          # The contents of the "intervalid" field.

        client_data, which can be  any Pop-11 object, replaces  whatever
        is in the  "client_data" field  of the structure  pointed to  by
        exptrclass.

        The procedure  referred  to  by widentproc,  which  should  be a
        Pop-11  TimeOut  procedure,  is  then  executed  by  a  call  to
        XptCallbackHandler with a TYPE of "timeout".




---------------------------------
5  Deferred Procedure Application
---------------------------------

When Poplog is in a wait state (e.g. waiting for input, or hibernating),
it passes  control  over the  the  Toolkit event  handlers.  All  Poplog
activity in this state occurs  via previously registered procedures  and
control only returns to 'top-level' Poplog  if there is an interrupt  or
an input on a relevant device. See Event Handling in REF * XTOOLKIT  for
a more detailed discussion of event handling.

However, what you should actually do in a callback is fairly  restricted
-- Toolkit event handling is not permitted (because the Toolkit handlers
are not  re-entrant), and  doing  any significant  amount of  work  in a
callback   is    deprecated.    To    avoid    this,    the    procedure
* external_defer_apply  (described  in  REF * EXTERNAL)  allows  you  to
specify actions in  a callback which  should be executed  only when  the
callback has "returned" to top-level Poplog.

The procedure XptSetXtWakeup may also be useful on occasions (note  that
this is run automatically  by external_defer_apply when called  inside a
Toolkit callback):

XptSetXtWakeup()                                             [procedure]
        This  procedure  is  intended   to  be  called  within   Toolkit
        callbacks. When Poplog is in  a wait state, waiting for  Toolkit
        events, calling XptSetXtWakeup causes  control to return to  the
        Poplog top-level at  the next convenient  point (i.e, after  all
        the callbacks  etc associated  with  the event  currently  being
        processed have been run).




--- C.x/x/pop/ref/xt_event
--- Copyright University of Sussex 1990. All rights reserved.
