   An "external client widget" is a widget that is part of another
program but functions as an Emacs screen.  This is intended to be a more
powerful replacement for standard text widgets.

Using an External Client Widget
*******************************

   The current implementation of the external client widget is designed
for use in a Motif application; thus it is a subclass of the base Motif
widget XmPrimitive.  In order to use an external client widget in a
client program, simply create an instance of widget type ExternalClient
and link your program with the library libexternalclient.a or
libexternalclient.so.  The corresponding header file is called
`ExternalClient.h'.

   The external client widget will not do anything until an instance of
Emacs is told about this particular widget.  To do that, call the
function `x-create-screen', passing as its second argument a string
containing the decimal representation of the widget's X window ID number
(this can be obtained by the Xt function `XtWindow()').  In order for
the client program to communicate this information to Emacs, a method
such as sending a ToolTalk message needs to be used.

   Once `x-create-screen' has been called, Emacs will create a screen
that occupies the client widget's window.  This screen can be used just
like any other screen in Emacs.

External Client Widget Resource Settings
****************************************

   The external client widget is a subclass of the Motif widget
XmPrimitive and thus inherits all its resources.  In addition, the
following new resources are defined:

`deadShell (class DeadShell)'
     A boolean resource indicating whether the last request to the
     ExternalShell widget that contains the screen corresponding to this
     widget timed out.  If true, no further requests will be made (all
     requests will automatically fail) until a response to the last
     request is received.  This resource should normally not be set by
     the user.

`shellTimeout (class ShellTimeout)'
     A value specifying how long (in milliseconds) the client should
     wait for a response when making a request to the corresponding
     ExternalShell widget.  If this timeout is exceeded, the client
     will assume that the shell is dead and will fail the request and
     all subsequent requests until a response to the request is
     received.  Default value is 5000, or 5 seconds.

   The shell that contains the screen corresponding to an external
client widget is of type ExternalShell, as opposed to standard screens,
whose shell is of type TopLevelShell.  The ExternalShell widget is a
direct subclass of Shell and thus inherits its resources.  In addition,
the following new resources are defined:

`window (class Window)'
     The X window ID of the widget to use for this Emacs screen.  This
     is normally set by the call to `x-create-screen' and should not be
     modified by the user.

`deadClient (class DeadClient)'
     A boolean resource indicating whether the last request to the
     corresponding ExternalClient widget timed out.  If true, no further
     requests will be made (all requests will automatically fail) until
     a response to the last request is received.  This resource should
     normally not be set by the user.

`ClientTimeout (class ClientTimeout)'
     A value specifying how long (in milliseconds) the shell should wait
     for a response when making a request to the corresponding
     ExternalClient widget.  If this timeout is exceeded, the shell
     will assume that the client is dead and will fail the request and
     all subsequent requests until a response to the request is
     received.  Default value is 5000, or 5 seconds.

   Note that the requests that are made between the client and the shell
are primarily for handling query-geometry and geometry-manager requests
made by parent or child widgets.

Motif-Specific Info About the External Client Widget
****************************************************

   By default, the external client widget has navigation type
`XmTAB_GROUP'.

   The widget traversal keystrokes are modified slightly from the
standard XmPrimitive keystrokes.  In particular, `TAB' alone does not
traverse to the next widget (`Ctrl-TAB' must be used instead), but
functions like a normal TAB in Emacs.  This follows the semantics of
the Motif text widget.  The traversal keystrokes `Ctrl-TAB' and
`Shift-TAB' are silently filtered by the external client widget and are
not seen by Emacs.