Reformatted.
[chise/xemacs-chise.git] / man / external-widget.texi
1 \input texinfo  @c -*-texinfo-*-
2 @setfilename ../info/external-widget.info
3
4 @ifinfo
5 @dircategory XEmacs Editor
6 @direntry
7 * External Widget: (external-widget) External Client Widget.
8 @end direntry
9 @end ifinfo
10
11 @node Top, Using an External Client Widget,, (dir)
12
13 An @dfn{external client widget} is a widget that is part of another program
14 but functions as an Emacs frame.  This is intended to be a more
15 powerful replacement for standard text widgets.
16
17 @menu
18 * Using an External Client Widget::
19 * External Client Widget Resource Settings::
20 * Motif-Specific Info About the External Client Widget::
21 * External Client Widget Internals::
22 @end menu
23
24
25 @node Using an External Client Widget, External Client Widget Resource Settings, Top, Top
26 @chapter Using an External Client Widget
27
28 There are three different implementations of the external client widget.
29 One is designed for use in Motif applications and is linked with the
30 option @code{-lextcli_Xm}.  Another is designed for non-Motif
31 applications that still use the X toolkit; it is linked with the option
32 @code{-lextcli_Xt}.  The third is designed for applications that do not
33 use the X toolkit; it is linked with the option @code{-lextcli_Xlib}.
34 In order to use an external client widget in a client program that uses
35 the X toolkit (i.e. either of the first two options described above),
36 simply create an instance of widget type ExternalClient and link your
37 program with the appropriate library.  The corresponding header file is
38 called @file{ExternalClient.h}.
39
40 Documentation still needs to be provided for using the raw Xlib
41 version of the external client widget.
42
43 The external client widget will not do anything until an instance of
44 Emacs is told about this particular widget.  To do that, call the
45 function @code{make-frame}, specifying a value for the frame parameter
46 @code{window-id}.  This value should be a string containing the decimal
47 representation of the widget's X window ID number (this can be obtained
48 by the Xt function @code{XtWindow()}).  In order for the client program
49 to communicate this information to Emacs, a method such as sending a
50 ToolTalk message needs to be used.
51
52 Once @code{make-frame} has been called, Emacs will create a frame
53 that occupies the client widget's window.  This frame can be used just
54 like any other frame in Emacs.
55
56
57 @node External Client Widget Resource Settings, Motif-Specific Info About the External Client Widget, Using an External Client Widget, Top
58 @chapter External Client Widget Resource Settings
59
60 The external client widget is a subclass of the Motif widget XmPrimitive
61 and thus inherits all its resources.  In addition, the following new
62 resources are defined:
63
64 @table @samp
65 @item deadShell (class DeadShell)
66 A boolean resource indicating whether the last request to the
67 ExternalShell widget that contains the frame corresponding to this
68 widget timed out.  If true, no further requests will be made (all
69 requests will automatically fail) until a response to the last
70 request is received.  This resource should normally not be set by the
71 user.
72
73 @item shellTimeout (class ShellTimeout)
74 A value specifying how long (in milliseconds) the client should wait
75 for a response when making a request to the corresponding ExternalShell
76 widget.  If this timeout is exceeded, the client will assume that the
77 shell is dead and will fail the request and all subsequent requests
78 until a response to the request is received.  Default value is 5000,
79 or 5 seconds.
80 @end table
81
82 The shell that contains the frame corresponding to an external client
83 widget is of type ExternalShell, as opposed to standard frames, whose
84 shell is of type TopLevelShell.  The ExternalShell widget is a direct
85 subclass of Shell and thus inherits its resources.  In addition, the
86 following new resources are defined:
87
88 @table @samp
89 @item window (class Window)
90 The X window ID of the widget to use for this Emacs frame.  This is
91 normally set by the call to @code{x-create-frame} and should not be
92 modified by the user.
93
94 @item deadClient (class DeadClient)
95 A boolean resource indicating whether the last request to the
96 corresponding ExternalClient widget timed out.  If true, no further
97 requests will be made (all requests will automatically fail) until a
98 response to the last request is received.  This resource should
99 normally not be set by the user.
100
101 @item ClientTimeout (class ClientTimeout)
102 A value specifying how long (in milliseconds) the shell should wait
103 for a response when making a request to the corresponding ExternalClient
104 widget.  If this timeout is exceeded, the shell will assume that the
105 client is dead and will fail the request and all subsequent requests
106 until a response to the request is received.  Default value is 5000,
107 or 5 seconds.
108 @end table
109
110 Note that the requests that are made between the client and the shell
111 are primarily for handling query-geometry and geometry-manager requests
112 made by parent or child widgets.
113
114
115 @node Motif-Specific Info About the External Client Widget, External Client Widget Internals, External Client Widget Resource Settings, Top
116 @chapter Motif-Specific Info About the External Client Widget
117
118 By default, the external client widget has navigation type
119 @samp{XmTAB_GROUP}.
120
121 The widget traversal keystrokes are modified slightly from the standard
122 XmPrimitive keystrokes.  In particular, @kbd{@key{TAB}} alone does not
123 traverse to the next widget (@kbd{Ctrl-@key{TAB}} must be used instead),
124 but functions like a normal @key{TAB} in Emacs.  This follows the
125 semantics of the Motif text widget.  The traversal keystrokes
126 @kbd{Ctrl-@key{TAB}} and @kbd{Shift-@key{TAB}} are silently filtered by
127 the external client widget and are not seen by Emacs.
128
129 @node External Client Widget Internals, , Motif-Specific Info About the External Client Widget, Top
130 @chapter External Client Widget Internals
131
132 The following text is lifted verbatim from Ben Wing's comments in
133 @file{ExternalShell.c}.
134
135 This is a special Shell that is designed to use an externally-
136 provided window created by someone else (possibly another process).
137 That other window should have an associated widget of class
138 ExternalClient.  The two widgets communicate with each other using
139 ClientMessage events and properties on the external window.
140
141 Ideally this feature should be independent of Emacs.  Unfortunately
142 there are lots and lots of specifics that need to be dealt with
143 for this to work properly, and some of them can't conveniently
144 be handled within the widget's methods.  Some day the code may
145 be rewritten so that the embedded-widget feature can be used by
146 any application, with appropriate entry points that are called
147 at specific points within the application.
148
149 This feature is similar to the OLE (Object Linking & Embedding)
150 feature provided by MS Windows.
151
152 Communication between this shell and the client widget:
153
154 Communication is through ClientMessage events with message_type
155 EXTW_NOTIFY and format 32.  Both the shell and the client widget
156 communicate with each other by sending the message to the same
157 window (the "external window" below), and the data.l[0] value is
158 used to determine who sent the message.
159
160 The data is formatted as follows:
161
162 data.l[0] = who sent this message: external_shell_send (0) or
163             external_client_send (1)
164 data.l[1] = message type (see enum en_extw_notify below)
165 data.l[2-4] = data associated with this message
166
167 EventHandler() handles messages from the other side.
168
169 extw_send_notify_3() sends a message to the other side.
170
171 extw_send_geometry_value() is used when an XtWidgetGeometry structure
172    needs to be sent.  This is too much data to fit into a
173    ClientMessage, so the data is stored in a property and then
174    extw_send_notify_3() is called.
175
176 extw_get_geometry_value() receives an XtWidgetGeometry structure from a
177    property.
178
179 extw_wait_for_response() is used when a response to a sent message
180    is expected.  It looks for a matching event within a
181    particular timeout.
182
183 The particular message types are as follows:
184
185 1) extw_notify_init (event_window, event_mask)
186
187 This is sent from the shell to the client after the shell realizes
188 its EmacsFrame widget on the client's "external window".  This
189 tells the client that it should start passing along events of the
190 types specified in event_mask.  event_window specifies the window
191 of the EmacsFrame widget, which is a child of the client's
192 external window.
193
194 extw_notify_init (client_type)
195
196 When the client receives an extw_notify_init message from the
197 shell, it sends back a message of the same sort specifying the type
198 of the toolkit used by the client (Motif, generic Xt, or Xlib).
199
200 2) extw_notify_end ()
201
202 This is sent from the shell to the client when the shell's
203 EmacsFrame widget is destroyed, and tells the client to stop
204 passing events along.
205
206 3) extw_notify_qg (result)
207
208 This is sent from the client to the shell when a QueryGeometry
209 request is received on the client.  The XtWidgetGeometry structure
210 specified in the QueryGeometry request is passed on in the
211 EXTW_QUERY_GEOMETRY property (of type EXTW_WIDGET_GEOMETRY) on the
212 external window.  result is unused.
213
214 In response, the shell passes the QueryGeometry request down the
215 widget tree, and when a response is received, sends a message of
216 type extw_notify_qg back to the client, with result specifying the
217 GeometryResult value.  If this value is XtGeometryAlmost, the
218 returned XtWidgetGeometry structure is stored into the same property
219 as above. [BPW is there a possible race condition here?]
220
221 4) extw_notify_gm (result)
222
223 A very similar procedure to that for extw_notify_qg is followed
224 when the shell's RootGeometryManager method is called, indicating
225 that a child widget wishes to change the shell's geometry.  The
226 XtWidgetGeometry structure is stored in the EXTW_GEOMETRY_MANAGER
227 property.
228
229 5) extw_notify_focus_in (), extw_notify_focus_out ()
230
231 These are sent from the client to the shell when the client gains
232 or loses the keyboard focus.  It is done this way because Xt
233 maintains its own concept of keyboard focus and only the client
234 knows this information.
235
236 @summarycontents
237 @contents
238 @bye