Mercurial > hg > xemacs-beta
annotate man/external-widget.texi @ 5142:f965e31a35f0
reduce lcrecord headers to 2 words, rename printing_unreadable_object
-------------------- ChangeLog entries follow: --------------------
man/ChangeLog addition:
2010-03-13 Ben Wing <ben@xemacs.org>
* internals/internals.texi (Working with Lisp Objects):
* internals/internals.texi (Writing Macros):
* internals/internals.texi (lrecords):
More rewriting to correspond with changes from
*LRECORD* to *LISP_OBJECT*.
modules/ChangeLog addition:
2010-03-13 Ben Wing <ben@xemacs.org>
* postgresql/postgresql.c (print_pgconn):
* postgresql/postgresql.c (print_pgresult):
printing_unreadable_object -> printing_unreadable_object_fmt.
2010-03-13 Ben Wing <ben@xemacs.org>
* ldap/eldap.c (print_ldap):
printing_unreadable_object -> printing_unreadable_object_fmt.
src/ChangeLog addition:
2010-03-13 Ben Wing <ben@xemacs.org>
* alloc.c (alloc_sized_lrecord_1):
* alloc.c (alloc_sized_lrecord_array):
* alloc.c (old_alloc_sized_lcrecord):
* alloc.c (disksave_object_finalization_1):
* alloc.c (mark_lcrecord_list):
* alloc.c (alloc_managed_lcrecord):
* alloc.c (free_managed_lcrecord):
* alloc.c (tick_lcrecord_stats):
* alloc.c (sweep_lcrecords_1):
* buffer.c (print_buffer):
* buffer.c (DEFVAR_BUFFER_LOCAL_1):
* casetab.c:
* casetab.c (print_case_table):
* console.c (print_console):
* console.c (DEFVAR_CONSOLE_LOCAL_1):
* data.c (print_weak_list):
* data.c (print_weak_box):
* data.c (print_ephemeron):
* data.c (ephemeron_equal):
* database.c (print_database):
* database.c (finalize_database):
* device-msw.c (sync_printer_with_devmode):
* device-msw.c (print_devmode):
* device-msw.c (finalize_devmode):
* device.c:
* device.c (print_device):
* elhash.c:
* elhash.c (print_hash_table):
* eval.c (print_subr):
* eval.c (print_multiple_value):
* event-stream.c (event_stream_resignal_wakeup):
* events.c (clear_event_resource):
* events.c (zero_event):
* events.c (print_event):
* extents.c:
* extents.c (print_extent):
* file-coding.c (print_coding_system):
* font-mgr.c:
* font-mgr.c (Ffc_init):
* frame.c:
* frame.c (print_frame):
* gc.c:
* gc.c (GC_CHECK_NOT_FREE):
* glyphs.c:
* glyphs.c (print_image_instance):
* glyphs.c (print_glyph):
* gui.c (print_gui_item):
* gui.c (copy_gui_item):
* keymap.c (print_keymap):
* keymap.c (MARKED_SLOT):
* lisp.h:
* lisp.h (struct Lisp_String):
* lisp.h (DEFUN):
* lisp.h (DEFUN_NORETURN):
* lrecord.h:
* lrecord.h (NORMAL_LISP_OBJECT_UID):
* lrecord.h (struct lrecord_header):
* lrecord.h (set_lheader_implementation):
* lrecord.h (struct old_lcrecord_header):
* lrecord.h (struct free_lcrecord_header):
* marker.c (print_marker):
* mule-charset.c:
* mule-charset.c (print_charset):
* objects.c (print_color_instance):
* objects.c (print_font_instance):
* objects.c (finalize_font_instance):
* print.c (print_cons):
* print.c (printing_unreadable_object_fmt):
* print.c (printing_unreadable_lisp_object):
* print.c (external_object_printer):
* print.c (internal_object_printer):
* print.c (debug_p4):
* print.c (ext_print_begin):
* process.c (print_process):
* rangetab.c (print_range_table):
* rangetab.c (range_table_equal):
* scrollbar.c (free_scrollbar_instance):
* specifier.c (print_specifier):
* specifier.c (finalize_specifier):
* symbols.c (guts_of_unbound_marker):
* symeval.h:
* symeval.h (DEFVAR_SYMVAL_FWD):
* tooltalk.c:
* tooltalk.c (print_tooltalk_message):
* tooltalk.c (print_tooltalk_pattern):
* ui-gtk.c (ffi_object_printer):
* ui-gtk.c (emacs_gtk_object_printer):
* ui-gtk.c (emacs_gtk_boxed_printer):
* window.c (print_window):
* window.c (free_window_mirror):
* window.c (debug_print_window):
* xemacs.def.in.in:
(1) printing_unreadable_object -> printing_unreadable_object_fmt.
(2) printing_unreadable_lcrecord -> printing_unreadable_lisp_object
and fix up so it no longer requires an lcrecord.
These previous changes eliminate most of the remaining places where
the terms `lcrecord' and `lrecord' occurred outside of specialized
code.
(3) Fairly major change: Reduce the number of words in an lcrecord
from 3 to 2. The third word consisted of a uid that duplicated the
lrecord uid, and a single free bit, which was moved into the lrecord
structure. This reduces the size of the `uid' slot from 21 bits to
20 bits. Arguably this isn't enough -- we could easily have more than
1,000,000 or so objects created in a session. The answer is
(a) It doesn't really matter if we overflow the uid field because
it's only used for debugging, to identify an object uniquely
(or pretty much so).
(b) If we cared about it overflowing and wanted to reduce this,
we could make it so that cons, string, float and certain other
frob-block types that never print out the uid simply don't
store a uid in them and don't increment the lrecord_uid_counter.
(4) In conjunction with (3), create new macro NORMAL_LISP_OBJECT_UID()
and use it to abstract out the differences between NEWGC and old-GC
in accessing the `uid' value from a "normal Lisp Object pointer".
(5) In events.c, use zero_nonsized_lisp_object() in place of custom-
written equivalent. In font-mgr.c use external_object_printer()
in place of custom-written equivalents.
author | Ben Wing <ben@xemacs.org> |
---|---|
date | Sat, 13 Mar 2010 05:38:08 -0600 |
parents | 03ab78e48ef6 |
children | ba07c880114a |
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 |
03ab78e48ef6
Add copyright and license information based on Ben's recollections.
Jerry James <james@xemacs.org>
parents:
863
diff
changeset
|
29 the Free Software Foundation, Inc., 51 Franklin St - Fifth Floor, |
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 |