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