XEmacs 21.2-b1
[chise/xemacs-chise.git.1] / man / external-widget.texi
1 \input texinfo  @c -*-texinfo-*-
2 @setfilename ../info/external-widget.info
3
4 @node Top, Using an External Client Widget,, (dir)
5
6 An @dfn{external client widget} is a widget that is part of another program
7 but functions as an Emacs frame.  This is intended to be a more
8 powerful replacement for standard text widgets.
9
10 @menu
11 * Using an External Client Widget::
12 * External Client Widget Resource Settings::
13 * Motif-Specific Info About the External Client Widget::
14 @end menu
15
16
17 @node Using an External Client Widget, External Client Widget Resource Settings, Top, Top
18 @chapter Using an External Client Widget
19
20 There are three different implementations of the external client widget.
21 One is designed for use in Motif applications and is linked with the
22 option @code{-lextcli_Xm}.  Another is designed for non-Motif
23 applications that still use the X toolkit; it is linked with the option
24 @code{-lextcli_Xt}.  The third is designed for applications that do not
25 use the X toolkit; it is linked with the option @code{-lextcli_Xlib}.
26 In order to use an external client widget in a client program that uses
27 the X toolkit (i.e. either of the first two options described above),
28 simply create an instance of widget type ExternalClient and link your
29 program with the appropriate library.  The corresponding header file is
30 called @file{ExternalClient.h}.
31
32 Documentation still needs to be provided for using the raw Xlib
33 version of the external client widget.
34
35 The external client widget will not do anything until an instance of
36 Emacs is told about this particular widget.  To do that, call the
37 function @code{make-frame}, specifying a value for the frame parameter
38 @code{window-id}.  This value should be a string containing the decimal
39 representation of the widget's X window ID number (this can be obtained
40 by the Xt function @code{XtWindow()}).  In order for the client program
41 to communicate this information to Emacs, a method such as sending a
42 ToolTalk message needs to be used.
43
44 Once @code{make-frame} has been called, Emacs will create a frame
45 that occupies the client widget's window.  This frame can be used just
46 like any other frame in Emacs.
47
48
49 @node External Client Widget Resource Settings, Motif-Specific Info About the External Client Widget, Using an External Client Widget, Top
50 @chapter External Client Widget Resource Settings
51
52 The external client widget is a subclass of the Motif widget XmPrimitive
53 and thus inherits all its resources.  In addition, the following new
54 resources are defined:
55
56 @table @samp
57 @item deadShell (class DeadShell)
58 A boolean resource indicating whether the last request to the
59 ExternalShell widget that contains the frame corresponding to this
60 widget timed out.  If true, no further requests will be made (all
61 requests will automatically fail) until a response to the last
62 request is received.  This resource should normally not be set by the
63 user.
64
65 @item shellTimeout (class ShellTimeout)
66 A value specifying how long (in milliseconds) the client should wait
67 for a response when making a request to the corresponding ExternalShell
68 widget.  If this timeout is exceeded, the client will assume that the
69 shell is dead and will fail the request and all subsequent requests
70 until a response to the request is received.  Default value is 5000,
71 or 5 seconds.
72 @end table
73
74 The shell that contains the frame corresponding to an external client
75 widget is of type ExternalShell, as opposed to standard frames, whose
76 shell is of type TopLevelShell.  The ExternalShell widget is a direct
77 subclass of Shell and thus inherits its resources.  In addition, the
78 following new resources are defined:
79
80 @table @samp
81 @item window (class Window)
82 The X window ID of the widget to use for this Emacs frame.  This is
83 normally set by the call to @code{x-create-frame} and should not be
84 modified by the user.
85
86 @item deadClient (class DeadClient)
87 A boolean resource indicating whether the last request to the
88 corresponding ExternalClient widget timed out.  If true, no further
89 requests will be made (all requests will automatically fail) until a
90 response to the last request is received.  This resource should
91 normally not be set by the user.
92
93 @item ClientTimeout (class ClientTimeout)
94 A value specifying how long (in milliseconds) the shell should wait
95 for a response when making a request to the corresponding ExternalClient
96 widget.  If this timeout is exceeded, the shell will assume that the
97 client is dead and will fail the request and all subsequent requests
98 until a response to the request is received.  Default value is 5000,
99 or 5 seconds.
100 @end table
101
102 Note that the requests that are made between the client and the shell
103 are primarily for handling query-geometry and geometry-manager requests
104 made by parent or child widgets.
105
106
107 @node Motif-Specific Info About the External Client Widget, , External Client Widget Resource Settings, Top
108 @chapter Motif-Specific Info About the External Client Widget
109
110 By default, the external client widget has navigation type
111 @samp{XmTAB_GROUP}.
112
113 The widget traversal keystrokes are modified slightly from the standard
114 XmPrimitive keystrokes.  In particular, @kbd{@key{TAB}} alone does not
115 traverse to the next widget (@kbd{Ctrl-@key{TAB}} must be used instead),
116 but functions like a normal @key{TAB} in Emacs.  This follows the
117 semantics of the Motif text widget.  The traversal keystrokes
118 @kbd{Ctrl-@key{TAB}} and @kbd{Shift-@key{TAB}} are silently filtered by
119 the external client widget and are not seen by Emacs.
120
121 @summarycontents
122 @contents
123 @bye