|
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::
|
|
750
|
22 * Example Program Using the External Client Widget::
|
|
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
|
|
750
|
116 @node Motif-Specific Info About the External Client Widget, Example Program Using the External Client Widget, 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
|
|
750
|
130
|
|
|
131 @node Example Program Using the External Client Widget, , Motif-Specific Info About the External Client Widget, Top
|
|
|
132 @chapter Example Program Using the External Client Widget
|
|
|
133
|
|
753
|
134 This is a very simple program. It has some issues with exiting.
|
|
|
135 Be careful to destroy the Emacs frame in the client window before
|
|
|
136 exiting the client program.
|
|
750
|
137
|
|
|
138 @example
|
|
|
139 /*
|
|
753
|
140 XEmacsInside.c
|
|
|
141
|
|
750
|
142 Copyright (C) 2002 Free Software Foundation
|
|
|
143
|
|
|
144 This program is part of XEmacs. XEmacs is free software. See the
|
|
|
145 file COPYING that came with XEmacs for conditions on redistribution.
|
|
|
146
|
|
|
147 This is an example of the XEmacs external widget facility.
|
|
|
148
|
|
|
149 It uses libextcli-Xt.a to interface to the X Toolkit Intrinsics.
|
|
|
150
|
|
|
151 Compile with
|
|
|
152
|
|
|
153 gcc -I/path/to/XEmacs/source/src -L/path/to/XEmacs/build/src -static \
|
|
|
154 -lextcli_Xt -lXt -lX11 -lSM -lICE \
|
|
|
155 -o XEmacsInside XEmacsInside.c
|
|
|
156
|
|
753
|
157 Run it with the resource "*input: True" and a reasonable geometry spec.
|
|
|
158 It pops up a window, and prints a Lisp form on stdout. Eval the form
|
|
|
159 in an XEmacs configured with --external-widget.
|
|
750
|
160
|
|
|
161 Written by Stephen J. Turnbull <stephen@@xemacs.org>
|
|
|
162
|
|
|
163 Based on simple_text.c from _The Motif Programming Manual_ by Heller
|
|
|
164 and Ferguson, O'Reilly.
|
|
|
165 */
|
|
|
166
|
|
|
167 #include <stdio.h>
|
|
|
168
|
|
|
169 #include <X11/Intrinsic.h>
|
|
|
170 #include <X11/StringDefs.h>
|
|
|
171 #include <X11/Shell.h>
|
|
|
172
|
|
|
173 #include "ExternalClient.h"
|
|
|
174
|
|
|
175 main (int argc, char *argv[])
|
|
755
|
176 @{
|
|
750
|
177 Widget toplevel, emacs;
|
|
|
178 XtAppContext app;
|
|
|
179
|
|
|
180 XtSetLanguageProc (NULL, NULL, NULL);
|
|
|
181
|
|
|
182 toplevel = XtVaOpenApplication (&app, "Demo",
|
|
|
183 NULL, 0, &argc, argv,
|
|
|
184 NULL, sessionShellWidgetClass,
|
|
|
185 NULL);
|
|
|
186
|
|
|
187 emacs = XtVaCreateManagedWidget ("externalWidget", externalClientWidgetClass,
|
|
|
188 toplevel,
|
|
|
189 NULL);
|
|
|
190
|
|
|
191 XtRealizeWidget (toplevel);
|
|
|
192
|
|
|
193 printf ("(make-frame '(window-id \"%d\"))\n", XtWindow(emacs));
|
|
|
194
|
|
|
195 XtAppMainLoop (app);
|
|
755
|
196 @}
|
|
750
|
197
|
|
|
198 /* This function doesn't belong here but somehow it's not getting resolved
|
|
|
199 from the library. */
|
|
|
200 void
|
|
|
201 fatal (char *msg)
|
|
755
|
202 @{
|
|
750
|
203 fprintf (stderr, "%s", msg);
|
|
|
204 exit (1);
|
|
755
|
205 @}
|
|
750
|
206 @end example
|
|
|
207
|
|
|
208
|
|
428
|
209 @summarycontents
|
|
|
210 @contents
|
|
|
211 @bye
|
