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

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

There are three different implementations of the external client widget. One is designed for use in Motif applications and is linked with the option -lextcli_Xm.  Another is designed for non-Motif applications that still use the X toolkit; it is linked with the option -lextcli_Xt.  The third is designed for applications that do not use the X toolkit; it is linked with the option -lextcli_Xlib. In order to use an external client widget in a client program that uses the X toolkit (i.e. either of the first two options described above), simply create an instance of widget type ExternalClient and link your program with the appropriate library.  The corresponding header file is called ExternalClient.h.

Documentation still needs to be provided for using the raw Xlib version of the external client widget.

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 make-frame, specifying a value for the frame parameter window-id.  This value should be 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 make-frame has been called, Emacs will create a frame that occupies the client widget's window.  This frame can be used just like any other frame 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 frame 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 frame corresponding to an external client widget is of type ExternalShell, as opposed to standard frames, 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 frame.  This is normally set by the call to x-create-frame 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.