Mercurial > hg > xemacs-beta
annotate man/external-widget.texi @ 5891:a0e751d6c3ad
Import the #'clear-string API from GNU, use it in tls.c
src/ChangeLog addition:
2015-04-18 Aidan Kehoe <kehoea@parhasard.net>
* sequence.c (Fclear_string): New, API from GNU. Zero a string's
contents, making sure the text is not kept around even when the
string's data is reallocated because of a changed character
length.
* sequence.c (syms_of_sequence): Make it available to Lisp.
* lisp.h: Make it available to C code.
* tls.c (nss_pk11_password): Use it.
* tls.c (gnutls_pk11_password): Use it.
* tls.c (openssl_password): Use it.
tests/ChangeLog addition:
2015-04-18 Aidan Kehoe <kehoea@parhasard.net>
* automated/lisp-tests.el:
Test #'clear-string, just added. Unfortunately there's no way to
be certain from Lisp that the old password data has been erased
after realloc; it may be worth adding a test to tests.c, but
*we'll be reading memory we shouldn't be*, so that gives me pause.
| author | Aidan Kehoe <kehoea@parhasard.net> |
|---|---|
| date | Sat, 18 Apr 2015 23:00:14 +0100 |
| parents | ba07c880114a |
| children |
| rev | line source |
|---|---|
| 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 |
|
4894
03ab78e48ef6
Add copyright and license information based on Ben's recollections.
Jerry James <james@xemacs.org>
parents:
863
diff
changeset
|
10 |
|
03ab78e48ef6
Add copyright and license information based on Ben's recollections.
Jerry James <james@xemacs.org>
parents:
863
diff
changeset
|
11 This file describes the external client widget for XEmacs. |
|
03ab78e48ef6
Add copyright and license information based on Ben's recollections.
Jerry James <james@xemacs.org>
parents:
863
diff
changeset
|
12 |
|
03ab78e48ef6
Add copyright and license information based on Ben's recollections.
Jerry James <james@xemacs.org>
parents:
863
diff
changeset
|
13 Copyright @copyright{} 1993 Ben Wing. |
|
03ab78e48ef6
Add copyright and license information based on Ben's recollections.
Jerry James <james@xemacs.org>
parents:
863
diff
changeset
|
14 |
|
03ab78e48ef6
Add copyright and license information based on Ben's recollections.
Jerry James <james@xemacs.org>
parents:
863
diff
changeset
|
15 This file is part of XEmacs. |
|
03ab78e48ef6
Add copyright and license information based on Ben's recollections.
Jerry James <james@xemacs.org>
parents:
863
diff
changeset
|
16 |
|
03ab78e48ef6
Add copyright and license information based on Ben's recollections.
Jerry James <james@xemacs.org>
parents:
863
diff
changeset
|
17 XEmacs is free software; you can redistribute it and/or modify it |
|
03ab78e48ef6
Add copyright and license information based on Ben's recollections.
Jerry James <james@xemacs.org>
parents:
863
diff
changeset
|
18 under the terms of the GNU General Public License as published by the |
|
03ab78e48ef6
Add copyright and license information based on Ben's recollections.
Jerry James <james@xemacs.org>
parents:
863
diff
changeset
|
19 Free Software Foundation; either version 2, or (at your option) any |
|
03ab78e48ef6
Add copyright and license information based on Ben's recollections.
Jerry James <james@xemacs.org>
parents:
863
diff
changeset
|
20 later version. |
|
03ab78e48ef6
Add copyright and license information based on Ben's recollections.
Jerry James <james@xemacs.org>
parents:
863
diff
changeset
|
21 |
|
03ab78e48ef6
Add copyright and license information based on Ben's recollections.
Jerry James <james@xemacs.org>
parents:
863
diff
changeset
|
22 XEmacs is distributed in the hope that it will be useful, but WITHOUT |
|
03ab78e48ef6
Add copyright and license information based on Ben's recollections.
Jerry James <james@xemacs.org>
parents:
863
diff
changeset
|
23 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
03ab78e48ef6
Add copyright and license information based on Ben's recollections.
Jerry James <james@xemacs.org>
parents:
863
diff
changeset
|
24 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
03ab78e48ef6
Add copyright and license information based on Ben's recollections.
Jerry James <james@xemacs.org>
parents:
863
diff
changeset
|
25 for more details. |
|
03ab78e48ef6
Add copyright and license information based on Ben's recollections.
Jerry James <james@xemacs.org>
parents:
863
diff
changeset
|
26 |
|
03ab78e48ef6
Add copyright and license information based on Ben's recollections.
Jerry James <james@xemacs.org>
parents:
863
diff
changeset
|
27 You should have received a copy of the GNU General Public License |
|
03ab78e48ef6
Add copyright and license information based on Ben's recollections.
Jerry James <james@xemacs.org>
parents:
863
diff
changeset
|
28 along with XEmacs; see the file COPYING. If not, write to |
|
5231
ba07c880114a
Fix up FSF's Franklin Street address in many files.
Stephen J. Turnbull <stephen@xemacs.org>
parents:
4894
diff
changeset
|
29 the Free Software Foundation, Inc., 51 Franklin Street - Fifth Floor, |
|
4894
03ab78e48ef6
Add copyright and license information based on Ben's recollections.
Jerry James <james@xemacs.org>
parents:
863
diff
changeset
|
30 Boston, MA 02110-1301, USA. |
| 428 | 31 @end ifinfo |
| 32 | |
| 33 @node Top, Using an External Client Widget,, (dir) | |
| 34 | |
| 35 An @dfn{external client widget} is a widget that is part of another program | |
| 36 but functions as an Emacs frame. This is intended to be a more | |
| 37 powerful replacement for standard text widgets. | |
| 38 | |
| 39 @menu | |
| 40 * Using an External Client Widget:: | |
| 41 * External Client Widget Resource Settings:: | |
| 42 * Motif-Specific Info About the External Client Widget:: | |
| 863 | 43 * External Client Widget Internals:: |
| 428 | 44 @end menu |
| 45 | |
| 46 | |
| 47 @node Using an External Client Widget, External Client Widget Resource Settings, Top, Top | |
| 48 @chapter Using an External Client Widget | |
| 49 | |
| 50 There are three different implementations of the external client widget. | |
| 51 One is designed for use in Motif applications and is linked with the | |
| 52 option @code{-lextcli_Xm}. Another is designed for non-Motif | |
| 53 applications that still use the X toolkit; it is linked with the option | |
| 54 @code{-lextcli_Xt}. The third is designed for applications that do not | |
| 55 use the X toolkit; it is linked with the option @code{-lextcli_Xlib}. | |
| 56 In order to use an external client widget in a client program that uses | |
| 57 the X toolkit (i.e. either of the first two options described above), | |
| 58 simply create an instance of widget type ExternalClient and link your | |
| 59 program with the appropriate library. The corresponding header file is | |
| 60 called @file{ExternalClient.h}. | |
| 61 | |
| 62 Documentation still needs to be provided for using the raw Xlib | |
| 63 version of the external client widget. | |
| 64 | |
| 65 The external client widget will not do anything until an instance of | |
| 66 Emacs is told about this particular widget. To do that, call the | |
| 67 function @code{make-frame}, specifying a value for the frame parameter | |
| 68 @code{window-id}. This value should be a string containing the decimal | |
| 69 representation of the widget's X window ID number (this can be obtained | |
| 70 by the Xt function @code{XtWindow()}). In order for the client program | |
| 71 to communicate this information to Emacs, a method such as sending a | |
| 72 ToolTalk message needs to be used. | |
| 73 | |
| 74 Once @code{make-frame} has been called, Emacs will create a frame | |
| 75 that occupies the client widget's window. This frame can be used just | |
| 76 like any other frame in Emacs. | |
| 77 | |
| 78 | |
| 79 @node External Client Widget Resource Settings, Motif-Specific Info About the External Client Widget, Using an External Client Widget, Top | |
| 80 @chapter External Client Widget Resource Settings | |
| 81 | |
| 82 The external client widget is a subclass of the Motif widget XmPrimitive | |
| 83 and thus inherits all its resources. In addition, the following new | |
| 84 resources are defined: | |
| 85 | |
| 86 @table @samp | |
| 87 @item deadShell (class DeadShell) | |
| 88 A boolean resource indicating whether the last request to the | |
| 89 ExternalShell widget that contains the frame corresponding to this | |
| 90 widget timed out. If true, no further requests will be made (all | |
| 91 requests will automatically fail) until a response to the last | |
| 92 request is received. This resource should normally not be set by the | |
| 93 user. | |
| 94 | |
| 95 @item shellTimeout (class ShellTimeout) | |
| 96 A value specifying how long (in milliseconds) the client should wait | |
| 97 for a response when making a request to the corresponding ExternalShell | |
| 98 widget. If this timeout is exceeded, the client will assume that the | |
| 99 shell is dead and will fail the request and all subsequent requests | |
| 100 until a response to the request is received. Default value is 5000, | |
| 101 or 5 seconds. | |
| 102 @end table | |
| 103 | |
| 104 The shell that contains the frame corresponding to an external client | |
| 105 widget is of type ExternalShell, as opposed to standard frames, whose | |
| 106 shell is of type TopLevelShell. The ExternalShell widget is a direct | |
| 107 subclass of Shell and thus inherits its resources. In addition, the | |
| 108 following new resources are defined: | |
| 109 | |
| 110 @table @samp | |
| 111 @item window (class Window) | |
| 112 The X window ID of the widget to use for this Emacs frame. This is | |
| 113 normally set by the call to @code{x-create-frame} and should not be | |
| 114 modified by the user. | |
| 115 | |
| 116 @item deadClient (class DeadClient) | |
| 117 A boolean resource indicating whether the last request to the | |
| 118 corresponding ExternalClient widget timed out. If true, no further | |
| 119 requests will be made (all requests will automatically fail) until a | |
| 120 response to the last request is received. This resource should | |
| 121 normally not be set by the user. | |
| 122 | |
| 123 @item ClientTimeout (class ClientTimeout) | |
| 124 A value specifying how long (in milliseconds) the shell should wait | |
| 125 for a response when making a request to the corresponding ExternalClient | |
| 126 widget. If this timeout is exceeded, the shell will assume that the | |
| 127 client is dead and will fail the request and all subsequent requests | |
| 128 until a response to the request is received. Default value is 5000, | |
| 129 or 5 seconds. | |
| 130 @end table | |
| 131 | |
| 132 Note that the requests that are made between the client and the shell | |
| 133 are primarily for handling query-geometry and geometry-manager requests | |
| 134 made by parent or child widgets. | |
| 135 | |
| 136 | |
| 863 | 137 @node Motif-Specific Info About the External Client Widget, External Client Widget Internals, External Client Widget Resource Settings, Top |
| 428 | 138 @chapter Motif-Specific Info About the External Client Widget |
| 139 | |
| 140 By default, the external client widget has navigation type | |
| 141 @samp{XmTAB_GROUP}. | |
| 142 | |
| 143 The widget traversal keystrokes are modified slightly from the standard | |
| 144 XmPrimitive keystrokes. In particular, @kbd{@key{TAB}} alone does not | |
| 145 traverse to the next widget (@kbd{Ctrl-@key{TAB}} must be used instead), | |
| 146 but functions like a normal @key{TAB} in Emacs. This follows the | |
| 147 semantics of the Motif text widget. The traversal keystrokes | |
| 148 @kbd{Ctrl-@key{TAB}} and @kbd{Shift-@key{TAB}} are silently filtered by | |
| 149 the external client widget and are not seen by Emacs. | |
| 150 | |
| 863 | 151 @node External Client Widget Internals, , Motif-Specific Info About the External Client Widget, Top |
| 152 @chapter External Client Widget Internals | |
| 750 | 153 |
| 863 | 154 The following text is lifted verbatim from Ben Wing's comments in |
| 155 @file{ExternalShell.c}. | |
| 750 | 156 |
| 863 | 157 This is a special Shell that is designed to use an externally- |
| 158 provided window created by someone else (possibly another process). | |
| 159 That other window should have an associated widget of class | |
| 160 ExternalClient. The two widgets communicate with each other using | |
| 161 ClientMessage events and properties on the external window. | |
| 750 | 162 |
| 863 | 163 Ideally this feature should be independent of Emacs. Unfortunately |
| 164 there are lots and lots of specifics that need to be dealt with | |
| 165 for this to work properly, and some of them can't conveniently | |
| 166 be handled within the widget's methods. Some day the code may | |
| 167 be rewritten so that the embedded-widget feature can be used by | |
| 168 any application, with appropriate entry points that are called | |
| 169 at specific points within the application. | |
| 753 | 170 |
| 863 | 171 This feature is similar to the OLE (Object Linking & Embedding) |
| 172 feature provided by MS Windows. | |
| 750 | 173 |
| 863 | 174 Communication between this shell and the client widget: |
| 750 | 175 |
| 863 | 176 Communication is through ClientMessage events with message_type |
| 177 EXTW_NOTIFY and format 32. Both the shell and the client widget | |
| 178 communicate with each other by sending the message to the same | |
| 179 window (the "external window" below), and the data.l[0] value is | |
| 180 used to determine who sent the message. | |
| 750 | 181 |
| 863 | 182 The data is formatted as follows: |
| 750 | 183 |
| 863 | 184 data.l[0] = who sent this message: external_shell_send (0) or |
| 185 external_client_send (1) | |
| 186 data.l[1] = message type (see enum en_extw_notify below) | |
| 187 data.l[2-4] = data associated with this message | |
| 750 | 188 |
| 863 | 189 EventHandler() handles messages from the other side. |
| 750 | 190 |
| 863 | 191 extw_send_notify_3() sends a message to the other side. |
| 750 | 192 |
| 863 | 193 extw_send_geometry_value() is used when an XtWidgetGeometry structure |
| 194 needs to be sent. This is too much data to fit into a | |
| 195 ClientMessage, so the data is stored in a property and then | |
| 196 extw_send_notify_3() is called. | |
| 197 | |
| 198 extw_get_geometry_value() receives an XtWidgetGeometry structure from a | |
| 199 property. | |
| 750 | 200 |
| 863 | 201 extw_wait_for_response() is used when a response to a sent message |
| 202 is expected. It looks for a matching event within a | |
| 203 particular timeout. | |
| 750 | 204 |
| 863 | 205 The particular message types are as follows: |
| 206 | |
| 207 1) extw_notify_init (event_window, event_mask) | |
| 750 | 208 |
| 863 | 209 This is sent from the shell to the client after the shell realizes |
| 210 its EmacsFrame widget on the client's "external window". This | |
| 211 tells the client that it should start passing along events of the | |
| 212 types specified in event_mask. event_window specifies the window | |
| 213 of the EmacsFrame widget, which is a child of the client's | |
| 214 external window. | |
| 215 | |
| 216 extw_notify_init (client_type) | |
| 750 | 217 |
| 863 | 218 When the client receives an extw_notify_init message from the |
| 219 shell, it sends back a message of the same sort specifying the type | |
| 220 of the toolkit used by the client (Motif, generic Xt, or Xlib). | |
| 750 | 221 |
| 863 | 222 2) extw_notify_end () |
| 223 | |
| 224 This is sent from the shell to the client when the shell's | |
| 225 EmacsFrame widget is destroyed, and tells the client to stop | |
| 226 passing events along. | |
| 750 | 227 |
| 863 | 228 3) extw_notify_qg (result) |
| 750 | 229 |
| 863 | 230 This is sent from the client to the shell when a QueryGeometry |
| 231 request is received on the client. The XtWidgetGeometry structure | |
| 232 specified in the QueryGeometry request is passed on in the | |
| 233 EXTW_QUERY_GEOMETRY property (of type EXTW_WIDGET_GEOMETRY) on the | |
| 234 external window. result is unused. | |
| 750 | 235 |
| 863 | 236 In response, the shell passes the QueryGeometry request down the |
| 237 widget tree, and when a response is received, sends a message of | |
| 238 type extw_notify_qg back to the client, with result specifying the | |
| 239 GeometryResult value. If this value is XtGeometryAlmost, the | |
| 240 returned XtWidgetGeometry structure is stored into the same property | |
| 241 as above. [BPW is there a possible race condition here?] | |
| 750 | 242 |
| 863 | 243 4) extw_notify_gm (result) |
| 750 | 244 |
| 863 | 245 A very similar procedure to that for extw_notify_qg is followed |
| 246 when the shell's RootGeometryManager method is called, indicating | |
| 247 that a child widget wishes to change the shell's geometry. The | |
| 248 XtWidgetGeometry structure is stored in the EXTW_GEOMETRY_MANAGER | |
| 249 property. | |
| 250 | |
| 251 5) extw_notify_focus_in (), extw_notify_focus_out () | |
| 252 | |
| 253 These are sent from the client to the shell when the client gains | |
| 254 or loses the keyboard focus. It is done this way because Xt | |
| 255 maintains its own concept of keyboard focus and only the client | |
| 256 knows this information. | |
| 750 | 257 |
| 428 | 258 @summarycontents |
| 259 @contents | |
| 260 @bye |