-This is ../info/external-widget.info, produced by makeinfo version 4.0
+This is ../info/external-widget.info, produced by makeinfo version 4.6
from external-widget.texi.
INFO-DIR-SECTION XEmacs Editor
* Using an External Client Widget::
* External Client Widget Resource Settings::
* Motif-Specific Info About the External Client Widget::
+* External Client Widget Internals::
\1f
File: external-widget.info, Node: Using an External Client Widget, Next: External Client Widget Resource Settings, Prev: Top, Up: Top
Using an External Client Widget
*******************************
- There are three different implementations of the external client
-widget. One is designed for use in Motif applications and is linked
-with the option `-lextcli_Xm'. Another is designed for non-Motif
-applications that still use the X toolkit; it is linked with the option
+There are three different implementations of the external client widget.
+One is designed for use in Motif applications and is linked with the
+option `-lextcli_Xm'. Another is designed for non-Motif applications
+that still use the X toolkit; it is linked with the option
`-lextcli_Xt'. The third is designed for applications that do not use
the X toolkit; it is linked with the option `-lextcli_Xlib'. In order
to use an external client widget in a client program that uses the X
External Client Widget Resource Settings
****************************************
- The external client widget is a subclass of the Motif widget
-XmPrimitive and thus inherits all its resources. In addition, the
-following new resources are defined:
+The external client widget is a subclass of the Motif widget XmPrimitive
+and thus inherits all its resources. In addition, the following new
+resources are defined:
`deadShell (class DeadShell)'
A boolean resource indicating whether the last request to the
made by parent or child widgets.
\1f
-File: external-widget.info, Node: Motif-Specific Info About the External Client Widget, Prev: External Client Widget Resource Settings, Up: Top
+File: external-widget.info, Node: Motif-Specific Info About the External Client Widget, Next: External Client Widget Internals, Prev: External Client Widget Resource Settings, Up: Top
Motif-Specific Info About the External Client Widget
****************************************************
- By default, the external client widget has navigation type
+By default, the external client widget has navigation type
`XmTAB_GROUP'.
The widget traversal keystrokes are modified slightly from the
`Shift-<TAB>' are silently filtered by the external client widget and
are not seen by Emacs.
+\1f
+File: external-widget.info, Node: External Client Widget Internals, Prev: Motif-Specific Info About the External Client Widget, Up: Top
+
+External Client Widget Internals
+********************************
+
+The following text is lifted verbatim from Ben Wing's comments in
+`ExternalShell.c'.
+
+ This is a special Shell that is designed to use an externally-
+provided window created by someone else (possibly another process).
+That other window should have an associated widget of class
+ExternalClient. The two widgets communicate with each other using
+ClientMessage events and properties on the external window.
+
+ Ideally this feature should be independent of Emacs. Unfortunately
+there are lots and lots of specifics that need to be dealt with for
+this to work properly, and some of them can't conveniently be handled
+within the widget's methods. Some day the code may be rewritten so
+that the embedded-widget feature can be used by any application, with
+appropriate entry points that are called at specific points within the
+application.
+
+ This feature is similar to the OLE (Object Linking & Embedding)
+feature provided by MS Windows.
+
+ Communication between this shell and the client widget:
+
+ Communication is through ClientMessage events with message_type
+EXTW_NOTIFY and format 32. Both the shell and the client widget
+communicate with each other by sending the message to the same window
+(the "external window" below), and the data.l[0] value is used to
+determine who sent the message.
+
+ The data is formatted as follows:
+
+ data.l[0] = who sent this message: external_shell_send (0) or
+ external_client_send (1) data.l[1] = message type (see enum
+en_extw_notify below) data.l[2-4] = data associated with this message
+
+ EventHandler() handles messages from the other side.
+
+ extw_send_notify_3() sends a message to the other side.
+
+ extw_send_geometry_value() is used when an XtWidgetGeometry structure
+ needs to be sent. This is too much data to fit into a
+ClientMessage, so the data is stored in a property and then
+extw_send_notify_3() is called.
+
+ extw_get_geometry_value() receives an XtWidgetGeometry structure
+from a property.
+
+ extw_wait_for_response() is used when a response to a sent message
+is expected. It looks for a matching event within a particular
+timeout.
+
+ The particular message types are as follows:
+
+ 1) extw_notify_init (event_window, event_mask)
+
+ This is sent from the shell to the client after the shell realizes
+its EmacsFrame widget on the client's "external window". This tells
+the client that it should start passing along events of the types
+specified in event_mask. event_window specifies the window of the
+EmacsFrame widget, which is a child of the client's external window.
+
+ extw_notify_init (client_type)
+
+ When the client receives an extw_notify_init message from the shell,
+it sends back a message of the same sort specifying the type of the
+toolkit used by the client (Motif, generic Xt, or Xlib).
+
+ 2) extw_notify_end ()
+
+ This is sent from the shell to the client when the shell's
+EmacsFrame widget is destroyed, and tells the client to stop passing
+events along.
+
+ 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.
+
\1f
Tag Table:
Node: Top\7f232
-Node: Using an External Client Widget\7f662
-Node: External Client Widget Resource Settings\7f2377
-Node: Motif-Specific Info About the External Client Widget\7f5120
+Node: Using an External Client Widget\7f699
+Node: External Client Widget Resource Settings\7f2410
+Node: Motif-Specific Info About the External Client Widget\7f5150
+Node: External Client Widget Internals\7f5961
\1f
End Tag Table