+\input texinfo @c -*-texinfo-*-
+@setfilename ../info/external-widget.info
+
+@node Top, Using an External Client Widget,, (dir)
+
+An @dfn{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.
+
+@menu
+* Using an External Client Widget::
+* External Client Widget Resource Settings::
+* Motif-Specific Info About the External Client Widget::
+@end menu
+
+
+@node Using an External Client Widget, External Client Widget Resource Settings, Top, Top
+@chapter 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 @code{-lextcli_Xm}. Another is designed for non-Motif
+applications that still use the X toolkit; it is linked with the option
+@code{-lextcli_Xt}. The third is designed for applications that do not
+use the X toolkit; it is linked with the option @code{-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 @file{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 @code{make-frame}, specifying a value for the frame parameter
+@code{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 @code{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 @code{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.
+
+
+@node External Client Widget Resource Settings, Motif-Specific Info About the External Client Widget, Using an External Client Widget, Top
+@chapter 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:
+
+@table @samp
+@item 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.
+
+@item 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.
+@end table
+
+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:
+
+@table @samp
+@item window (class Window)
+The X window ID of the widget to use for this Emacs frame. This is
+normally set by the call to @code{x-create-frame} and should not be
+modified by the user.
+
+@item 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.
+
+@item 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.
+@end table
+
+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.
+
+
+@node Motif-Specific Info About the External Client Widget, , External Client Widget Resource Settings, Top
+@chapter Motif-Specific Info About the External Client Widget
+
+By default, the external client widget has navigation type
+@samp{XmTAB_GROUP}.
+
+The widget traversal keystrokes are modified slightly from the standard
+XmPrimitive keystrokes. In particular, @kbd{@key{TAB}} alone does not
+traverse to the next widget (@kbd{Ctrl-@key{TAB}} must be used instead),
+but functions like a normal @key{TAB} in Emacs. This follows the
+semantics of the Motif text widget. The traversal keystrokes
+@kbd{Ctrl-@key{TAB}} and @kbd{Shift-@key{TAB}} are silently filtered by
+the external client widget and are not seen by Emacs.
+
+@summarycontents
+@contents
+@bye
projects / chise / xemacs-chise.git.1 / blobdiff