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