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