X-Git-Url: http://git.chise.org/gitweb/?p=chise%2Fxemacs-chise.git.1;a=blobdiff_plain;f=man%2Fexternal-widget.texi;fp=man%2Fexternal-widget.texi;h=40ccb5ccd5aa8c06d2085f4c2c3d04afba164863;hp=0000000000000000000000000000000000000000;hb=6883ee56ec887c2c48abe5b06b5e66aa74031910;hpb=5db996688c255b7f4bbe096f935b10d4c4ab7ade diff --git a/man/external-widget.texi b/man/external-widget.texi new file mode 100644 index 0000000..40ccb5c --- /dev/null +++ b/man/external-widget.texi @@ -0,0 +1,123 @@ +\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