xemacs-beta: man/external-widget.texi comparison

comparison man/external-widget.texi @ 863:42375619fa45

[xemacs-hg @ 2002-06-04 06:03:59 by andyp] merge 21.4 windows changes, minimally tested

author	andyp
date	Tue, 04 Jun 2002 06:05:53 +0000
parents	da44ff90109f
children	03ab78e48ef6

comparison

equal deleted inserted replaced

-:278c743f1578
+:42375619fa45
 @menu
 * Using an External Client Widget::
 * External Client Widget Resource Settings::
 * Motif-Specific Info About the External Client Widget::
-* Example Program Using the External Client Widget::
+* External Client Widget Internals::
 @end menu
 @node Using an External Client Widget, External Client Widget Resource Settings, Top, Top
 @chapter Using an External Client Widget
 Note that the requests that are made between the client and the shell
 are primarily for handling query-geometry and geometry-manager requests
 made by parent or child widgets.
-@node Motif-Specific Info About the External Client Widget, Example Program Using the External Client Widget, External Client Widget Resource Settings, Top
+@node Motif-Specific Info About the External Client Widget, External Client Widget Internals, External Client Widget Resource Settings, Top
 @chapter Motif-Specific Info About the External Client Widget
 By default, the external client widget has navigation type
 @samp{XmTAB_GROUP}.
 but functions like a normal @key{TAB} in Emacs.  This follows the
 semantics of the Motif text widget.  The traversal keystrokes
 @kbd{Ctrl-@key{TAB}} and @kbd{Shift-@key{TAB}} are silently filtered by
 the external client widget and are not seen by Emacs.
+@node External Client Widget Internals, , Motif-Specific Info About the External Client Widget, Top
-@node Example Program Using the External Client Widget, , Motif-Specific Info About the External Client Widget, Top
+@chapter External Client Widget Internals
-@chapter Example Program Using the External Client Widget
+The following text is lifted verbatim from Ben Wing's comments in
-This is a very simple program.  It has some issues with exiting.
+@file{ExternalShell.c}.
-Be careful to destroy the Emacs frame in the client window before
-exiting the client program.
+This is a special Shell that is designed to use an externally-
+provided window created by someone else (possibly another process).
-@example
+That other window should have an associated widget of class
-/*
+ExternalClient.  The two widgets communicate with each other using
-XEmacsInside.c
+ClientMessage events and properties on the external window.
-Copyright (C) 2002 Free Software Foundation
+Ideally this feature should be independent of Emacs.  Unfortunately
+there are lots and lots of specifics that need to be dealt with
-This program is part of XEmacs.  XEmacs is free software.  See the
+for this to work properly, and some of them can't conveniently
-file COPYING that came with XEmacs for conditions on redistribution.
+be handled within the widget's methods.  Some day the code may
+be rewritten so that the embedded-widget feature can be used by
-This is an example of the XEmacs external widget facility.
+any application, with appropriate entry points that are called
+at specific points within the application.
-It uses libextcli-Xt.a to interface to the X Toolkit Intrinsics.
+This feature is similar to the OLE (Object Linking & Embedding)
-Compile with
+feature provided by MS Windows.
-gcc -I/path/to/XEmacs/source/src -L/path/to/XEmacs/build/src -static \
+Communication between this shell and the client widget:
--lextcli_Xt -lXt -lX11 -lSM -lICE \
--o XEmacsInside XEmacsInside.c
+Communication is through ClientMessage events with message_type
+EXTW_NOTIFY and format 32.  Both the shell and the client widget
-Run it with the resource "*input: True" and a reasonable geometry spec.
+communicate with each other by sending the message to the same
-It pops up a window, and prints a Lisp form on stdout.  Eval the form
+window (the "external window" below), and the data.l[0] value is
-in an XEmacs configured with --external-widget.
+used to determine who sent the message.
-Written by Stephen J. Turnbull <stephen@@xemacs.org>
+The data is formatted as follows:
-Based on simple_text.c from _The Motif Programming Manual_ by Heller
+data.l[0] = who sent this message: external_shell_send (0) or
-and Ferguson, O'Reilly.
+external_client_send (1)
-*/
+data.l[1] = message type (see enum en_extw_notify below)
+data.l[2-4] = data associated with this message
-#include <stdio.h>
+EventHandler() handles messages from the other side.
-#include <X11/Intrinsic.h>
-#include <X11/StringDefs.h>
+extw_send_notify_3() sends a message to the other side.
-#include <X11/Shell.h>
+extw_send_geometry_value() is used when an XtWidgetGeometry structure
-#include "ExternalClient.h"
+needs to be sent.  This is too much data to fit into a
+ClientMessage, so the data is stored in a property and then
-main (int argc, char *argv[])
+extw_send_notify_3() is called.
-@{
-Widget toplevel, emacs;
+extw_get_geometry_value() receives an XtWidgetGeometry structure from a
-XtAppContext app;
+property.
-XtSetLanguageProc (NULL, NULL, NULL);
+extw_wait_for_response() is used when a response to a sent message
+is expected.  It looks for a matching event within a
-toplevel = XtVaOpenApplication (&app, "Demo",
+particular timeout.
-				  NULL, 0, &argc, argv,
-				  NULL, sessionShellWidgetClass,
+The particular message types are as follows:
-				  NULL);
+1) extw_notify_init (event_window, event_mask)
-emacs = XtVaCreateManagedWidget ("externalWidget", externalClientWidgetClass,
-				   toplevel,
+This is sent from the shell to the client after the shell realizes
-				   NULL);
+its EmacsFrame widget on the client's "external window".  This
+tells the client that it should start passing along events of the
-XtRealizeWidget (toplevel);
+types specified in event_mask.  event_window specifies the window
+of the EmacsFrame widget, which is a child of the client's
-printf ("(make-frame '(window-id \"%d\"))\n", XtWindow(emacs));
+external window.
-XtAppMainLoop (app);
+extw_notify_init (client_type)
-@}
+When the client receives an extw_notify_init message from the
-/* This function doesn't belong here but somehow it's not getting resolved
+shell, it sends back a message of the same sort specifying the type
-from the library. */
+of the toolkit used by the client (Motif, generic Xt, or Xlib).
-void
-fatal (char *msg)
+2) extw_notify_end ()
-@{
-fprintf (stderr, "%s", msg);
+This is sent from the shell to the client when the shell's
-exit (1);
+EmacsFrame widget is destroyed, and tells the client to stop
-@}
+passing events along.
-@end example
+3) extw_notify_qg (result)
+This is sent from the client to the shell when a QueryGeometry
+request is received on the client.  The XtWidgetGeometry structure
+specified in the QueryGeometry request is passed on in the
+EXTW_QUERY_GEOMETRY property (of type EXTW_WIDGET_GEOMETRY) on the
+external window.  result is unused.
+In response, the shell passes the QueryGeometry request down the
+widget tree, and when a response is received, sends a message of
+type extw_notify_qg back to the client, with result specifying the
+GeometryResult value.  If this value is XtGeometryAlmost, the
+returned XtWidgetGeometry structure is stored into the same property
+as above. [BPW is there a possible race condition here?]
+4) extw_notify_gm (result)
+A very similar procedure to that for extw_notify_qg is followed
+when the shell's RootGeometryManager method is called, indicating
+that a child widget wishes to change the shell's geometry.  The
+XtWidgetGeometry structure is stored in the EXTW_GEOMETRY_MANAGER
+property.
+5) extw_notify_focus_in (), extw_notify_focus_out ()
+These are sent from the client to the shell when the client gains
+or loses the keyboard focus.  It is done this way because Xt
+maintains its own concept of keyboard focus and only the client
+knows this information.
 @summarycontents
 @contents
 @bye

Mercurial > hg > xemacs-beta

comparison man/external-widget.texi @ 863:42375619fa45